Internal objects must include XML documentation comments
A developer creates an internal object, assuming that because it is not public, documentation is unnecessary. However, internal objects are often consumed by other objects within the same extension, or by other extensions via InternalsVisibleTo. Without XML documentation, consumers see the object in IntelliSense with no description and no guidance on its responsibilities, constraints, or intended usage.
Add XML documentation comments to describe the internal object and how it should be used, or restrict it further if it is not meant to be reused.
Example
The following object is internal and lacks XML documentation:
codeunit 50100 MyCodeunit // Internal objects must include XML documentation comments [DC0008]
{
Access = Internal;
// [...]
}Add XML documentation to describe the internal object’s purpose:
/// <summary>
/// Provides shared internal functionality for calculating totals and related operations.
/// </summary>
codeunit 50100 MyCodeunit
{
Access = Internal;
// [...]
}If the object is not meant to be consumed by other objects, consider reducing its visibility (for example, by moving logic into local procedures inside a more appropriate object).
When the diagnostic is reported
- The object is declared with
Access = Internal. - The object has no XML documentation comments immediately preceding its declaration.
Code documentation comments
The AL Language extension has built-in IntelliSense support for XML documentation comments
: typing /// above an object declaration generates a template with a <summary> tag. Code documentation comments are available since Business Central 2020 Release Wave 2 (version 17)
.
Exception
Test objects (for example, test codeunits with Subtype = Test) are exempt. Internal test objects do not require XML documentation.