XML Documentation Comments

Go Up to Code Editor

Overview

XML Documentation comments are:

• Introduced with a triple-slash (///).
• Structured using XML tags.
• Folded and unfolded like a regular code block or region (see Using Code Folding.)
• Supported by Delphi.

XML Doc comments are displayed in Help Insight (if parsed successfully) and, also, are included by the compiler when generating XML Documentation (as devnotes XML elements).

The XML tags must be properly closed, such as <para>...</para>. If a closing element is not found, then the XML representation is invalid and Help Insight is not able to display the XML comments.

Example of a Delphi function with XML Documentation comments

/// <summary> Removes the specified item from the collection
/// </summary>
/// <param name="Item">The item to remove
/// </param>
/// <param name="Collection">The group containing the item
/// </param>
/// <remarks>
/// If parameter "Item" is null, an exception is raised.
/// <see cref="EArgumentNilException"/>
/// </remarks>
/// <returns>True if the specified item is successfully removed;
/// otherwise False is returned.
/// </returns>
function RemoveItem(Item: Pointer; Collection: Pointer): Boolean;
begin
  // Non-XML DOC comment
  // ...
end;

For more examples of XML DOC comments, see the following source files:

• DSServer.pas
• DSCommonServer.pas
• DSHTTP.pas

XML Elements

You can use the following elements in XML DOC comments:

<summary>

A summary of the target function or class

<para>

A paragraph

<c>

Text in fixed-width font

<code>

Preformatted text, such as source code

<remarks>

Remarks regarding the target function or class

<param name="ParameterName">

The name and description of a specific parameter

<see>

Reference to a specific type, symbol, or identifier

<returns>

Description of the return value of the target function. For example, the function might return an error code.

<exception cref="EExceptionTypeName">

Exception that can be thrown by a method

<permission cref="PermissionType">

Permissions for a method

See Also

• XML documentation comments (C# programming guide)
• XML Documentation for C++ Code (Compiler-generated XML Documentation)
• Using Code Folding