From ffe06c5ff5a4059bed1cfc27547d7afdc64d269c Mon Sep 17 00:00:00 2001 From: Carsten Scholling Date: Mon, 7 Sep 2026 05:19:59 +0200 Subject: [PATCH] docs(DC0004,DC0009): clarify control add-in documentation requirements - Explain that control add-in procedures cannot be restricted to local or internal scope. - Document DC0009 coverage for undocumented control add-in event declarations. - Add a control add-in event example and align the reporting conditions with the analyzer. --- .../docs/analyzers/DocumentationCop/DC0004.md | 8 ++++++-- .../docs/analyzers/DocumentationCop/DC0009.md | 18 ++++++++++++++---- 2 files changed, 20 insertions(+), 6 deletions(-) diff --git a/content/docs/analyzers/DocumentationCop/DC0004.md b/content/docs/analyzers/DocumentationCop/DC0004.md index 7f0f9f7..bb973c7 100644 --- a/content/docs/analyzers/DocumentationCop/DC0004.md +++ b/content/docs/analyzers/DocumentationCop/DC0004.md @@ -12,7 +12,7 @@ linkTitle = 'DC0004' 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](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-xml-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. +Add [XML documentation comments](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-xml-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 @@ -46,7 +46,7 @@ codeunit 50100 MyCodeunit } {{< /highlight >}} -If the procedure is not meant to be called externally, restrict its scope instead: +If a codeunit procedure is not meant to be called externally, restrict its scope instead: {{< highlight al "hl_lines=3" >}} codeunit 50100 MyCodeunit @@ -64,6 +64,10 @@ codeunit 50100 MyCodeunit - 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](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-xml-comments): typing `///` above a procedure generates a template with ``, ``, and `` tags matching the signature. Code documentation comments are available since [Business Central 2020 Release Wave 2 (version 17)](https://learn.microsoft.com/en-us/previous-versions/dynamics365-release-plan/2020wave2/smb/dynamics365-business-central/code-documentation-comments). diff --git a/content/docs/analyzers/DocumentationCop/DC0009.md b/content/docs/analyzers/DocumentationCop/DC0009.md index 6cc1cb5..975f183 100644 --- a/content/docs/analyzers/DocumentationCop/DC0009.md +++ b/content/docs/analyzers/DocumentationCop/DC0009.md @@ -10,7 +10,7 @@ linkTitle = 'DC0009' ignoreObsolete = true +++ -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. +A developer exposes an event by declaring an event in a control add-in or by decorating a codeunit procedure with `[IntegrationEvent(false, false)]` or `[BusinessEvent(false, false)]`, assuming its 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](https://learn.microsoft.com/dynamics365/business-central/dev-itpro/developer/devenv-xml-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. @@ -50,9 +50,19 @@ codeunit 50100 MyCodeunit ### 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`. +- An event is declared in a control add-in, or a procedure is decorated with `[IntegrationEvent()]` or `[BusinessEvent()]`. +- The event or procedure has no XML documentation comments. + +### Control add-ins + +The following control add-in event is public and lacks XML documentation: + +{{< highlight al "hl_lines=3" >}} +controladdin MyControlAddIn +{ + event ControlAddInReady() // Events must include XML documentation comments [DC0009] +} +{{< /highlight >}} ### Code documentation comments