建議用於 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。
- 用於多個元素的一般標記 - 這些標記是任何 API 的基本集。
- 用於成員的標記 - 記載方法和屬性時,會使用這些標記。
<returns>
:此元素的值會顯示在 Visual Studio 的 IntelliSense 中。<param>
*:此元素的值會顯示在 Visual Studio 的 IntelliSense 中。<paramref>
<exception>
*<value>
:此元素的值會顯示在 Visual Studio 的 IntelliSense 中。
- 格式化文件輸出 - 這些標記提供工具的格式化指示,而這些工具會產生文件。
- 重複使用文件文字 - 這些標記所提供的工具可讓您更輕鬆地重複使用 XML 註解。
<inheritdoc>
**<include>
*
- 產生連結和參考 - 這些標記會產生其他文件的連結。
- 泛型類型和方法的標記 - 這些標記僅適用於泛型類型和方法
<typeparam>
*:此元素的值會顯示在 Visual Studio 的 IntelliSense 中。<typeparamref>
注意
文件註解不能套用至命名空間。
如果您想要讓角括弧出現在文件註解的文字中,則請使用 <
和 >
的 HTML 編碼,其分別為 <
和 >
。 此編碼顯示於下列範例中。
/// <summary>
/// This property always returns a value < 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>
區塊所指定。 針對每個item
,您只需要提供description
的項目。
建立定義清單時:
- 您必須提供標題中
term
的項目。 - 清單中的每個項目都是使用
<item>
區塊所指定。 每個item
都必須同時包含term
和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 中的項目名稱。 將成員置於引號 (") 內。 您可以使用個別的結尾標記,以針對 "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 的多個輸出格式。