針對 c # 檔批註建議 XML 標記

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

以下是在 c # 程式碼中使用 XML 檔標記時,您應該知道的一些建議、一般使用案例和事項。 雖然您可以將任何標籤放入檔批註中,但本文會說明最常見語言結構的建議標記。 在所有情況下,您都應該遵守這些建議:

  • 為了達成一致性,所有公開可見的類型及其公用成員都應記載。
  • 也可以使用 XML 註解記錄私用成員。 不過,它會公開內部 (可能會有機密) 的程式庫運作。
  • 類型和其成員最少應該具有 <summary> 標記,因為 IntelliSense 需要其內容。
  • 應該使用結尾為句號的完整句子來撰寫文件文字。
  • 部分類別完全受支援,而且檔資訊將會串連為每個類型的單一專案。

XML 檔的開頭為 /// 。 當您建立新專案時,範本會為您放入一些入門 /// 行。 這些註解在處理時有一些限制:

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

      注意

      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> 。 這項資訊會顯示在 [物件瀏覽器] 視窗中。 此標記可能包含更冗長的說明。 您可能會發現使用 CDATA 區段進行 markdown 會讓撰寫更為方便。 Docfx之類的工具會處理章節中的 markdown 文字 CDATA

檔成員

<returns>

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

<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> 區塊來指定。 建立定義清單時,您必須同時指定 termdescription 。 不過,針對資料表、項目符號清單或編號清單,您只需要提供 description 的項目。 清單或資料表可以視需要擁有多個 <item> 區塊。

<c>

<c>text</c>

<c>標記可讓您表示描述中的文字應標示為程式碼。 用 <code> 來指出多行程式碼。

<code>

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

<code>標記用來指出多行程式碼。 用 <c> 來表示描述中的單行文字應標示為程式碼。

<example>

<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 語法。 請參閱 XPath 檔以取得自訂您的 <include> 使用方式。

<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> 會產生可點按的連結,其中包含連結的文字 GitHub https://github.com
  • langword="keyword":語言關鍵字,例如 true

<see>標記可讓您指定文字內的連結。 使用 <seealso> 以指出文字應放置在 [另請參閱] 區段中。 使用 cref 屬性 可建立程式碼專案之檔頁面的內部超連結。 您可以包含類型參數,以指定泛型型別或方法的參考,例如 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> 會產生可點按的連結,其中包含連結的文字 GitHub https://github.com

<seealso>標記可讓您指定您可能想要在 [另請參閱] 區段中顯示的文字。 用 <see> 來指定文字內的連結。 您無法在 seealso 標記內嵌套標記 summary

cref 屬性

cref 屬性在 XML 文件標記中表示「程式碼參考」。 它會指定標記的內部文字是程式碼項目,例如類型、方法或屬性。 DocFXSandcastle 這類文件工具使用 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 的多個輸出格式。