LC0072

The documentation comment must match the procedure syntax

This rule ensures that documentation comments in the AL code accurately reflect the corresponding procedure's syntax, parameters, and return value.

Scenarios Checked by the Rule

The following cases will trigger a diagnostic:

1. Mismatched <returns> Tag:

• A <returns> documentation comment exists, but the procedure does not return a value.
• A <returns> documentation comment is missing, but the procedure does return a value.

2. Mismatched <param> Tags:

• A <param name="parameterName"> documentation comment exists, but the procedure does not have a parameter named parameterName.
• A <param name="parameterName"> documentation comment is missing, but the procedure has a parameter named parameterName.
• The parameter name in the <param> tag differs from the actual parameter name in the procedure.

Examples

/// <summary>
/// Documentation comment parameter but no procedure parameter.
/// </summary>
/// <param name="Value">The value.</param> // LC0072: The documentation comment must match the procedure syntax.
procedure NoParameter()
begin

end;

/// <summary>
/// Procedure parameter but no documentation comment parameter.
/// </summary>
procedure ParameterButNoComment(Value: Boolean) // LC0072: The documentation comment must match the procedure syntax.
begin

end;

/// <summary>
/// Parameter name mismatch.
/// </summary>
/// <param name="NotMyValue">The value.</param> // LC0072: The documentation comment must match the procedure syntax.
procedure NameMissmatch(Value: Boolean) // LC0072: The documentation comment must match the procedure syntax.
begin

end;

Current Limitations

The rule does not validate the <paramref> element (<paramref name="parameterName"/>), which is occasionally used in XML documentation. Adding support for this would require additional processing but could be considered for future improvements if needed.

Read more

• Original discussion