Muokkaa

Jaa

Documenting your code with XML comments

  • Artikkeli

APPLIES TO: Business Central 2020 release wave 2 and later

In Dynamics 365 Business Central, you can add documentation directly in your source code by including XML elements in special comment fields before the block of code that the comment refers to. The documentation comment must immediately precede a user-defined type that it annotates, for example a codeunit, table, interface, or a member such as a field or method. The syntax for adding XML comments in your code is triple slashes /// followed by one of the supported XML tags. There's IntelliSense support for writing documentation comments that also provides a template comment on entering the third slash in the triple slash.

Documentation comments are visible when you hover over source symbols, in completion lists, and in signature help. By adding XML comments in code, you can improve readability, add useful information about the implementation, and help others take over code that you wrote. With XML comments, you also enable IntelliSense in Visual Studio Code on the AL objects that you add in the code as a help to other developers, working with or extending your code. When your code is documented using XML comments, it means that when you've built an extension and someone extends this code, they get inline documentation when they call the given object. Finally, XML comments are used to generate help files for your extension by using the ALDoc tool, learn more in the Autogenerating documentation section below.

Note

If you have the allowDownloadingSource setting in the app.json file set to false and you then download an app package; the app package won't contain any XML comments.

Supported XML tags

The following table lists the XML elements that are supported for AL.

Top-level XML Tag Description Syntax
<summary> A summary of the object <summary>description</summary>
<param> Used in method declarations to describe one or more parameters defined in the method. For each parameter, specify the name and a description. <param name="name">description</param>
<returns> Used in method declarations to describe the return value of the method. <returns>description</returns>
<example> Used to specify an example of how to use a given codeunit or object. <example>description</example>
<remarks> Used to supplement information given in the <summary> section. <remarks>description</remarks>
Formatting XML Tag Description Syntax
<paramref> Specifies a reference to a parameter in a <summary> or <remarks> block. <paramref name="name"/>
<para> Allows structuring text inside a <summary>, <remarks>, or <returns> tag. <para>paragraph</para>
<b> Allows formatting text as bold inside a top-level tag. <b>bold</b>
<i> Allows formatting text as italic inside a top-level tag. <i>italic</i>
<c> Specifies that text within a description should be marked as code inside a top-level tag. <c>inline code</c>
<code> Specifies that multiline text within a description should be marked as code inside a top-level tag. <code>code block</code>
<list> Specifies a list formatted as a bulleted or numbered list, or as a table in a <summary> or <remarks> block. <list type="bullet|number|table">. See full List syntax below.

List syntax


<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

Example

The following example is taken from the Email.Codeunit.al file in the System Application. In this example, the parameter EmailMessageId is documented using the <param> syntax.

/// <summary>
/// Provides functionality to create and send e-mails.
/// </summary>

codeunit 8901 "Email"
{
    Access = Public;

    /// <summary>
    /// Enqueues an email in the outbox to be sent in the background.
    /// </summary>
    /// <param name="EmailMessageId">The ID of the email to enqueue</param>
    procedure Enqueue(EmailMessageId: Guid)
    begin
        EmailImpl.Enqueue(EmailMessageId);
    end;
...

Special symbols

For special symbols, such as angle brackets, to appear in text of a documentation comment, use the HTML encoding of < and >, which is &lt; and &gt; respectively. The following example illustrates how.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

Writing tips

Code comments improve the readability of the code that you've developed and they're useful for anyone modifying or maintaining that code. Furthermore, code comments form the basis of autogenerated documentation. Great code comments must do the following:

  1. Never state the obvious.
  2. Write a meaningful comment, use precise wording to describe why.
  3. Imagine yourself in the shoes of the developer using this piece of code, what would you want to know?
  4. For properties and methods, use active wording such as Sets..., Gets..., and Specifies..., and then explain what it does.
  5. List all preconditions for your parameters (can't be null, must be within a certain range, and so on).
  6. List any post-conditions that could influence how callers deal with return values.
  7. List any exceptions the method might throw (and under what circumstances).
  8. If similar methods exist, explain the differences between them.
  9. Call attention to anything unexpected (such as modifying global state).
  10. Enumerate any side-effects, if there are any.
  11. Be consistent.
  12. Be concise.
  13. Make sure that your comments are reviewed.

For more examples, see https://stackoverflow.com/questions/3143324/what-are-best-practices-for-documenting-c-sharp-code-with-xml-comments.

Autogenerating documentation

You can use the ALDoc tool, which comes with the AL Language extension for Visual Studio Code to generate documentation from your XML comments. Learn more in Generating help with the ALDoc tool.

AL development environment
Developing extensions in AL
Pages overview
Microsoft writing style guide