Generate XML documentation comments for AL language in Visual Studio Code and generate markdown files from Source Code.

Type /// in AL source code, it auto-generates an context aware XML documentation comment like this:

In addition to the regular documentation activity you can:

• Add new lines in existing XML Documentation comment section. (/// will automatically added.)
• Use Snippets directly inside the XML Documentation comment section.

There are two commands available to generate markdown files from XML documentation:

Note
All commands start with AL DOC prefix to make it easier to find them.

Generate markdown documentation files, based on the XML documentation in AL source code. For each object file (e.g. MyCodeunit.Codeunit.al) a subdirectory inside the export directory will be created. Each procedure and trigger method is creating a single file (e.g. DoSomething.al) inside the subdirectory. Additionally an index file (index.md) will be created per object file and contains a list of every documented element in the source file.

Note
This feature exports all valid XML documentation from objects with access modifier Public (or not set) and Subtype Normal (or not set).

Additionally warnings will be shown in the output channel in Visual Studio Code to show missing documentations.

If enableSummaryHover configuration is activated (default) every time hovering over a procedure in your AL source code the XML documentation in the source file or symbols will be searched and presented as tooltip.

Note
Currently only procedures are supported and only the <summary> tag will be presented as tooltip.

Important
Due to possible accessibility limitations of symbol files (showmycode in AL project app.json, etc.) it's not possible to retrieve the XML documentation comments for dependencies in this case.

If checkProcedureDocumentation configuration is activated (default) every AL source file in current workspace will be checked for complete procedure documentation. Incomplete or missing procedure documentations are added as diagnostic entries (information level) and providing quick fix actions to solve.

Currently the following diagnostic codes and associated actions are implemented:

Three snippets are included into the extension:

docsummary snippet adds simple <summary> xml documentation comment:

    /// <summary>
    /// This is the description of a specific procedure, trigger or object.
    /// </summary>

docexamplecode snippet adds <example> xml documentation comment:

    /// <example>
    /// This is the description of an example
    /// <code>
    /// if (i <> y) then
    ///   DoSomething(i, y);
    /// </code>
    /// </example>

docremarks snippet adds <remarks> xml documentation comment:

    /// <remarks>
    /// This are some specific remarks for the documented procedure.
    /// </remarks>

1. Install Visual Studio Code 1.44.0 or higher
2. Launch Visual Studio Code
3. From the extension view Ctrl-Shift-X (Windows, Linux) or Cmd-Shift-X (macOS)
4. Search and Choose the extension AL XML Documentation
5. Reload Visual Studio Code

The menu under File > Preferences (Code > Preferences on Mac) provides entries to configure user and workspace settings.

The following configuration parameters are available:

Important
The object directory (e.g. doc\mycodeunit.codeunit.al\) will be deleted if already exist.

{
    "bdev-al-xml-doc.markdown_path": "C:/Documentation/",
    "bdev-al-xml-doc.verbose": true,
    "bdev-al-xml-doc.exportScope": "all",
    "bdev-al-xml-doc.enableSummaryHover": true    
}

This extension is only processing AL language source code files.

Object Type	Supported
procedure
local procedure
internal procedure
trigger

Note
The purpose of the AL XML Documentation is to document your AL Source Code, not to document structures, controls or table fields.

Therefor it's currently not planned to add support for AL keywords, other the currently supported.

Object Type	Supported
codeunit
table
page
enum
xmlport
interface
table extension
page extension
enum extension
page customization
profile

XML Tag	Supported
summary
param
returns
remarks
example

• Visual Studio Code 1.44.0 (or higher) - Download here
• .NET Core 3.0 (or higher) - Download here

This extension is licensed under the MIT License.