Public procedures must include XML documentation comments

Properties

DC0004 Info Design Code Fix Ignore Obsolete

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. A codeunit procedure that is not meant to be part of the public API can instead be restricted to local or internal scope.

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 a codeunit 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.

Control add-ins

Procedures declared in a control add-in are part of the public usercontrol contract. AL does not permit local or internal modifiers for these members, so XML documentation is the only way to satisfy DC0004.

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.