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>

<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# 程式設計指南）