Hi, Readers.
Today I would like to briefly talk about documentation comments in Business Central.
APPLIES TO: Business Central 2020 release wave 2 and later (BC17)
In Dynamics 365 Business Central, you can add documentation to your code by including XML elements in special comment fields directly in the source code 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, or 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 is IntelliSense support for writing documentation comments. Most importantly providing a template documentation comment when writing the third slash in the triple slash.
We can look at the standard codeunit.
codeunit 8901 “Email”
When we call it:
Codeunit:
Method (procedure):
PS: In overloaded procedures
Let’s look at another example.
codeunit 1284 “Password Handler”
Codeunit:
Method (procedure):
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. |
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 < and > respectively. The following example illustrates how.
For example,
Writing tips
Code comments improve the readability of the code that you have developed and they are very useful for anyone modifying or maintaining that code. Furthermore, code comments form the basis of auto-generated documentation. Great code comments must do the following:
- Never state the obvious.
- Write a meaningful comment, use precise wording to describe why.
- Imagine yourself in the shoes of the developer using this piece of code, what would you want to know?
- For properties and methods, use active wording such as Sets…, Gets…, and Specifies…, and then explain what it does.
- List all pre-conditions for your parameters (cannot be null, must be within a certain range, and so on).
- List any post-conditions that could influence how callers deal with return values.
- List any exceptions the method may throw (and under what circumstances).
- If similar methods exist, explain the differences between them.
- Call attention to anything unexpected (such as modifying global state).
- Enumerate any side-effects, if there are any.
- Be consistent.
- Be concise.
- 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.
Adding XML Documentation can greatly improve the readability of our code. Give it a try!!!😁
You can find more details about XML Comments in Code in MS Docs.
PS: If you have the the AL XML Documentation extension installed.
You may see the following message.
XML documentation is expected for Procedure TestPermission.
or
XML documentation is expected for Object Lab Book.
You can disable it in the following settings, or change it to Warning or Error.
Check Object Documentation Information Level:
Check Procedure Documentation Information Level
END
Hope this will help.
Thanks.
ZHU
コメント