Events must include XML documentation comments

Properties
DC0009 Hidden Design Code Fix Ignore Obsolete

A developer adds an event procedure to a codeunit and decorates it with [IntegrationEvent(false, false)] or [BusinessEvent(false, false)], assuming the event name and parameters will be self-explanatory. For consumers of the extension — especially those without access to the source code — the event appears in IntelliSense with no description, no parameter hints, and no information about when it is raised or how it should be handled. They are left to guess at its purpose, preconditions, and guarantees.

Add XML documentation comments to describe the event, its parameters, and its intended usage, or remove the event if it is not meant to be part of the public API.

Example

The following event is exposed as an integration event and lacks XML documentation:

codeunit 50100 MyCodeunit
{
    [IntegrationEvent(false, false)]
    local procedure OnBeforeCalculateTotal(Quantity: Decimal; UnitPrice: Decimal; var IsHandled: Boolean) // Events must include XML documentation comments [DC0009]
    begin
    end;
}

Add XML documentation to describe when the event is raised and how subscribers should use it:

codeunit 50100 MyCodeunit
{
    /// <summary>
    /// Raised before the total price is calculated, allowing subscribers to override the default calculation.
    /// </summary>
    /// <param name="Quantity">The number of units used in the calculation.</param>
    /// <param name="UnitPrice">The price per unit used in the calculation.</param>
    /// <param name="IsHandled">
    /// Set to <c>true</c> by subscribers to indicate that the calculation has been handled and the default logic should be skipped.
    /// </param>
    [IntegrationEvent(false, false)]
    procedure OnBeforeCalculateTotal(Quantity: Decimal; UnitPrice: Decimal; var IsHandled: Boolean)
    begin
    end;
}

When the diagnostic is reported

  • The procedure is decorated with [IntegrationEvent()] or [BusinessEvent()].
  • The procedure has no XML documentation comments.
  • The containing object has an accessibility of Public.

Code documentation comments

The AL Language extension has built-in IntelliSense support for XML documentation comments : typing /// above an event procedure generates a template with <summary> and <param> 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. Event procedures in test codeunits do not require XML documentation.

See also

  • DC0006 — Internal procedures must include XML documentation comments
  • DC0010 — Internal events must include XML documentation comments