delphi XML 文档注释

XML 文档注释

概述

XML文档注释包括：

• 以三斜杠 (///) 引入。
• 使用 XML 标签结构化。
• 像常规代码块或区域一样折叠和展开（请参阅 使用代码折叠。）
• Delphi支持。

XML文档注释显示在 Help Insight 中（如果解析成功），并且在生成 XML 文档（作为 devnotes XML 元素）时由编译器包含。

XML 标签必须正确关闭，例如 <para>...</para>。如果未找到结束元素，则 XML 表示无效并且 Help Insight 无法显示 XML 注释。

带有 XML 文档注释的 Delphi 函数示例

/// <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;

有关 XML DOC 注释的更多示例，请参阅以下源文件：

• FMX.Controls.pas
• FMX.Forms.pas
• FMX.ListView.pas

XML 元素

可以在XML文档注释中使用以下元素：

<summary>

目标函数或类的摘要

<para>

一个段落，用于标签内部，例如 <summary>、<remarks> 或 <returns>

<para> 标签创建一个双倍行距的段落。 <br/>标签创建一个单行距段落。

<br/>

换行，用于标签内部，例如 <summary>、<remarks> 或 <returns>

<c>

固定宽度字体的文本，标签用于表示单行代码

<code>

预格式化文本，标签用于表示多行代码

<remarks>

关于目标函数或类的备注，补充用 <summary> 指定的信息

<param name="ParameterName">

特定参数的名称和描述

name 方法参数的名称。 用双引号 " " 将名称括起来

<see cref="member">

对特定类型、符号或标识符的引用

cref 表示“代码参考”， 它指定标记的内部文本是代码元素，例如类型、方法或属性

<returns>

目标函数的返回值说明。 例如，该函数可能会返回错误代码

<exception cref="EExceptionTypeName">

方法可能引发的异常

cref 对当前编译环境中可用的异常的引用

<permission cref="PermissionType">

方法的权限

<b>

粗体文本

<i>

斜体文本

<u>

下划线

例子

    /// <summary>测试函数
    /// <br/><b>类信息</b><see cref="Unit1.TForm1">TForm1</see>
    /// </summary>
    /// <param name="I">Integer类型参数</param>
    /// <param name="S">string类型参数</param>
    /// <returns><c>True</c>执行成功 <c>False</c>执行失败</returns>
    /// <exception cref="异常类">输入参数错误</exception>
    /// <remarks> 函数补充信息
    /// <para>调用例子：</para>
    /// <code>CeShi(1, 'aa');</code>
    /// </remarks>
    function CeShi(I: Integer; S: string): Boolean;

参考

XML 文档注释（C# 编程指南）