Public procedures must include XML documentation comments

A developer adds a public procedure to a codeunit, expecting the procedure name and parameters to speak for themselves. For consumers of the extension — especially those without access to the source code — the procedure appears in IntelliSense with no description, no parameter hints, and no return-value documentation. They are left to guess at its purpose, preconditions, and guarantees.

Add XML documentation comments to describe the procedure, or restrict it to local or internal scope if it is not meant to be part of the public API.

Example

The following procedure is public but lacks XML documentation:

codeunit 50100 MyCodeunit
{
    procedure CalculateTotal(Quantity: Decimal; UnitPrice: Decimal): Decimal // Public procedures must include XML documentation comments [DC0004]
    begin
        exit(Quantity * UnitPrice);
    end;
}

Add XML documentation to describe the procedure’s purpose, parameters, and return value:

codeunit 50100 MyCodeunit
{
    /// <summary>
    /// Calculates the total price based on quantity and unit price.
    /// </summary>
    /// <param name="Quantity">The number of units.</param>
    /// <param name="UnitPrice">The price per unit.</param>
    /// <returns>The total price.</returns>
    procedure CalculateTotal(Quantity: Decimal; UnitPrice: Decimal): Decimal
    begin
        exit(Quantity * UnitPrice);
    end;
}

If the procedure is not meant to be called externally, restrict its scope instead:

codeunit 50100 MyCodeunit
{
    local procedure CalculateTotal(Quantity: Decimal; UnitPrice: Decimal): Decimal
    begin
        exit(Quantity * UnitPrice);
    end;
}

When the diagnostic is reported

• The procedure has no local or internal keyword.
• The procedure has no XML documentation comments.
• The containing object has public accessibility (the default for codeunits). Procedures in a codeunit with Access = Internal are not flagged, because they are not part of the extension’s public API.

Code documentation comments

The AL Language extension has built-in IntelliSense support for XML documentation comments : typing /// above a procedure generates a template with <summary>, <param>, and <returns> tags matching the signature. Code documentation comments are available since Business Central 2020 Release Wave 2 (version 17) .

Exception

Test codeunits (Subtype = Test) are exempt. Procedures in test codeunits — including test methods and handler methods — do not require XML documentation.

See also

• DC0005 — XML documentation must match the procedure signature