建議用於 C# 文件註解的 XML 標記

  • 發行項

C# 文件註解使用 XML 元素來定義輸出文件的結構。 此功能的其中一個結果是您可以在文件註解中新增任何有效的 XML。 C# 編譯器會將這些元素複製至輸出 XML 檔案。 雖然您可以在註解中使用任何有效的 XML (包括任何有效的 HTML 元素)，但基於許多原因，建議您記載程式碼。

接下來是一些建議、一般使用案例，以及在 C# 程式碼中使用 XML 文件標記時應該知道的事項。 雖然您可以將任何標記放入您的文件註解，但本文描述最常見語言建構的建議標記。 在所有情況下，您應該遵守這些建議：

  • 為保持一致性，應該記載所有公開可見的類型和其成員。
  • 也可以使用 XML 註解記錄私用成員。 不過，這會公開您程式庫的內部 (可能是機密) 運作。
  • 類型與其成員至少應該具有 <summary> 標籤。
  • 應該使用結尾為句號的完整句子來撰寫文件文字。
  • 完全支援部分類別，而且文件資訊將會串連為每種類型的單一項目。

XML 文件的開頭是 ///。 當您建立新的專案時，範本會為您在開頭放入幾行 ///。 這些註解在處理時有一些限制：

  • 文件必須是語式正確的 XML。 如果 XML 格式不正確，則編譯器會產生警告。 文件檔案將會包含註解，指出發生錯誤。
  • 其中一些建議的標記具有特殊意義：
    • <param> 標記用來描述參數。 如果使用，編譯器會驗證參數存在，而且所有參數在文件中都有描述。 如果驗證失敗，則編譯器會發出警告。
    • cref 屬性可以附加至任何標記，以參考程式碼元素。 編譯器會驗證此程式碼項目存在。 如果驗證失敗，則編譯器會發出警告。 編譯器在尋找 cref 屬性中所述的類型時，會遵守任何 using 陳述式。
    • Visual Studio 中的 IntelliSense 使用 <summary> 標記來顯示類型或成員的其他資訊。

      注意

      XML 檔案不會提供類型和成員的完整資訊 (例如，它不會包含任何類型資訊)。 若要取得類型或成員的完整資訊，請搭配使用文件檔案與實際類型或成員上的反映。

  • 開發人員可以自由建立自己的標記集合。 編譯器會將這些項目複製至輸出檔案。

某些建議標記可以用於任何語言元素。 其他則具有更具體的使用方式。 最後，某些標記用來格式化文件中的文字。 本文描述依使用方式組織的建議標記。

編譯器會驗證下列清單中後面接著單一 * 的元素的語法。 Visual Studio 為編譯器所驗證的標記提供 IntelliSense，以及下列清單中後面接著 ** 的所有標記。 除了此處所列的標記之外，編譯器和 Visual Studio 還會驗證 <b>、<i>、<u>、<br/> 和 <a> 標記。 編譯器也會驗證 <tt>，而這是已遭取代的 HTML。

注意

文件註解不能套用至命名空間。

如果您想要讓角括弧出現在文件註解的文字中，則請使用 < 和 > 的 HTML 編碼，其分別為 &lt; 和 &gt;。 此編碼顯示於下列範例中。

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

一般標記

<summary>

<summary>description</summary>

<summary> 標記應該用來描述類型或類型成員。 使用 <remarks> 來新增類型描述的補充資訊。 使用 cref 屬性，讓 DocFX 和 Sandcastle 這類文件工具針對程式碼元素建立文件頁面的內部超連結。 <summary> 標籤的文字會顯示在 IntelliSense 和 [物件瀏覽器] 視窗中。

<remarks>

<remarks>
description
</remarks>

<remarks> 標記用來新增類型或類型成員的相關資訊，以補充使用 <summary> 所指定的資訊。 這項資訊會顯示在 [物件瀏覽器] 視窗中。 此標記可能包括更為冗長的說明。 您可能會發現使用 Markdown 的 CDATA 區段，讓其撰寫更為方便。 docfx 這類工具會處理 CDATA 區段中的 Markdown 文字。

文件成員

<傳回>

<returns>description</returns>

<returns> 標記應該用於方法宣告的註解中，以描述傳回值。

<param>

<param name="name">description</param>
  • name：方法參數的名稱。 以雙引號 (" ") 括住名稱。 參數的名稱必須符合 API 簽章。 如果未涵蓋一或多個參數，則編譯器會發出警告。 如果 name 的值不符合方法宣告中的正式參數，則編譯器也會發出警告。

<param> 標記應該用於方法宣告的註解中，以描述該方法的其中一個參數。 若要記載多個參數，請使用多個 <param> 標記。 <param> 標記的文字會顯示在 IntelliSense、物件瀏覽器和程式碼註解 Web 報告中。

<paramref>

<paramref name="name"/>
  • name：要參照的參數名稱。 以雙引號 (" ") 括住名稱。

<paramref> 標記提供一種方法來表示在程式碼註解中的字組，例如 <summary> 或 <remarks> 區塊中的字組指的是參數。 若要以某種不同方式 (例如，粗體或斜體字型) 格式化這個字組，您可以處理 XML 檔案。

<exception>

<exception cref="member">description</exception>
  • cref = "member"：可從目前編譯環境所取得例外狀況的參考。 編譯器會檢查指定的例外狀況是否存在，並將 member 轉譯為輸出 XML 中的標準項目名稱。 member 必須出現在雙引號內 (" ")。

<exception> 標記可讓您指定可以擲回的例外狀況。 這個標記可以套用至方法、屬性、事件和索引子的定義。

<value>

<value>property-description</value>

<value> 標記可讓您描述屬性所代表的值。 當您在 Visual Studio .NET 開發環境中透過程式碼精靈新增屬性時，會新增新屬性的 <summary> 標記。 您可以手動新增 <value> 標記，以描述屬性所代表的值。

格式化文件輸出

<para>

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

<para> 標記用於 <summary>、<remarks> 或 <returns> 這類標記，並可讓您新增文字的結構。 <para> 標記會建立雙空格段落。 如果您想要單一空格段落，則請使用 <br/> 標記。

<清單>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
</list>

<listheader> 區塊用來定義資料表或定義清單的標題資料列。 定義資料表時，您只需要提供標題中 term 的項目。 清單中的每個項目都是使用 <item> 區塊所指定。 建立定義清單時，您需要同時指定 term 和 description。 不過，針對資料表、項目符號清單或編號清單，您只需要提供 description 的項目。 清單或資料表可以有所需的多個 <item> 區塊。

<c>

<c>text</c>

<c> 標記可讓您指出應該將描述內的文字標記為程式碼。 使用 <code>，以將多行指定為程式碼。

<code>

<code>
    var index = 5;
    index++;
</code>

<code> 標記用來指出多行程式碼。 使用 <c>，以指出描述內的單行文字應該標記為程式碼。

<範例>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

<example> 標記可讓您指定如何使用方法或其他程式庫成員的範例。 範例通常需要使用 <code> 標記。

重複使用文件文字

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

繼承基底類別、介面和類似方法的 XML 註解。 使用 inheritdoc 可消除不想要的重複 XML 註解複製和貼上，並自動讓 XML 註解保持同步。 請注意，當您將 <inheritdoc> 標記新增至類型時，所有成員也都會繼承註解。

  • cref：指定要向其繼承文件的成員。 繼承的標記不會覆寫目前成員上已定義的標記。
  • path：將會導致顯示節點集的 XPath 運算式查詢。 您可以使用此屬性來篩選標記，以包括或排除繼承的文件。

在基底類別或介面中新增 XML 註解，並讓 inheritdoc 將註解複製至實作類別。 將 XML 註解新增至同步方法，並讓 inheritdoc 將註解複製至相同方法的非同步版本。 如果您想要從特定成員複製註解，則請使用 cref 屬性來指定成員。

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename：包含文件的 XML 檔案名稱。 檔案名稱可以採用的原始程式碼檔的相對路徑。 請將 filename 括在單引號 (' ') 內。
  • tagpath：filename 中導致 name 標記的標記路徑。 請將路徑括在單引號 (' ') 內。
  • name：標記中位在註解前面的名稱規範；name 將會有 id。
  • id：位在註解前面的標記識別碼。 請將識別碼括在雙引號 (" ") 內。

<include> 標記可讓您參考另一個檔案中描述原始程式碼中類型和成員的註解。 包括外部檔案是將文件註解直接放在原始程式碼檔案中的替代方案。 將文件放入個別檔案，即可將原始檔控制套用至與原始程式碼不同的文件。 一個人可以簽出原始程式碼檔，而且其他人可以簽出文件檔。<include> 標記使用 XML XPath 語法。 如需自訂 <include> 用法的方式，請參閱 XPath 文件。

例如，下列原始程式碼會使用 <include> 標籤來包含備註。 檔案路徑是相對於來源的。

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

Include 檔案的 XML 來源會顯示在下列範例中。 其結構與 C# 編譯器所產生的 XML 檔案相同。 XML 檔案可以包含多個方法或類型的文字，只要 XPath 運算式可以識別它們即可。

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

此方法的 XML 輸出會顯示在下列範例中：

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

提示

.NET 執行階段小組會在其文件中廣泛使用 <include> 標籤。 您可以藉由搜尋 dotnet/runtime 存放庫來查看許多範例。

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member"：可從目前編譯環境呼叫的成員或欄位參考。 編譯器會檢查指定的程式碼項目是否存在，並將 member 傳遞給輸出 XML 中的項目名稱。 將 member 置於雙引號 (" ") 內。 您可以使用個別的結尾標記，以針對 "cref" 提供不同的連結文字。
  • href="link"：給定 URL 的可按一下連結。 例如，<see href="https://github.com">GitHub</see> 會產生可按一下連結，其中包含連結至 https://github.com 的文字 GitHub。
  • langword="keyword"：語言關鍵字，例如 true 或其中一個其他有效關鍵字。

<see> 標記可讓您在文字內指定連結。 使用 <seealso>，以指出文字應該放置於＜請參閱＞一節中。 使用 cref 屬性，以針對程式碼元素建立文件頁面的內部超連結。 您可以包括類型參數，以指定泛型類型或方法的參考，例如 cref="IDictionary{T, U}"。 此外，href 是將作為超連結的有效屬性。

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member"：可從目前編譯環境呼叫的成員或欄位參考。 編譯器會檢查指定的程式碼項目是否存在，並將 member 傳遞給輸出 XML 中的項目名稱。 member 必須出現在雙引號內 (" ")。
  • href="link"：給定 URL 的可按一下連結。 例如，<seealso href="https://github.com">GitHub</seealso> 會產生可按一下連結，其中包含連結至 https://github.com 的文字 GitHub。

<seealso> 標記可讓您指定要顯示在＜請參閱＞一節中的文字。 使用 <see>，以在文字內指定連結。 您無法在 summary 標記內巢狀 seealso 標記。

cref 屬性

cref 屬性在 XML 文件標記中表示「程式碼參考」。它會指定標記的內部文字是程式碼項目，例如類型、方法或屬性。 DocFX 和 Sandcastle 這類文件工具使用 cref 屬性自動產生記錄類型或成員的頁面超連結。

href 屬性

href 屬性表示網頁的參考。 您可以使用它直接參考 API 或程式庫的線上文件。

泛型類型和方法

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult：類型參數的名稱。 以雙引號 (" ") 括住名稱。

<typeparam> 標記應該用於泛型型別或方法宣告的註解中，以描述型別參數。 新增泛型型別或方法之每個型別參數的標記。 <typeparam> 標記的文字將會顯示在 IntelliSense 中。

<typeparamref>

<typeparamref name="TKey"/>
  • TKey：類型參數的名稱。 以雙引號 (" ") 括住名稱。

使用這個標記，讓文件檔案的取用者以某種明顯方式格式化單字，例如斜體。

使用者定義標記

所有以上所述的標記都代表 C# 編譯器所辨識的標記。 不過，使用者可以定義自己的標記。 Sandcastle 這類工具支援 <event> 和 <note> 這類額外標記，甚至支援記載命名空間。 自訂或內部文件產生工具也可以與標準標記搭配使用，而且可以支援從 HTML 到 PDF 的多個輸出格式。