使用 XML 批註記錄程式代碼

發行項
12/17/2024

您可以從 F# 中的三斜線（//）程式代碼批注產生檔。 XML 註解可以出現在程式碼檔案（.fs）或簽名檔案（.fsi）的宣告之前。

XML 文件註釋是一種特殊的註釋，新增至任何使用者自訂類型或成員的定義上方。它們很特別，因為編譯器可以在編譯期間處理它們來生成 XML 文件檔。編譯程式產生的 XML 檔案可以與您的 .NET 元件一起散發，讓 IDE 可以使用工具提示來顯示類型或成員的快速資訊。此外，XML 檔案可以透過 fsdocs 之類的工具來執行，以產生 API 參考網站。

編譯程式預設會忽略 XML 檔批注。若要變更此設定，請設為 --warnon:3390。編譯程式接著會驗證 XML 的語法，以及 <param> 和 <paramref> 標記中所參考的參數。

您可以執行下列其中一項動作，在編譯階段產生 XML 檔案：

您可以將 GenerateDocumentationFile 元素新增到 <PropertyGroup> 專案檔的 .fsproj 區段，此動作會在專案目錄中產生一個 XML 檔案，其根檔名與組件相同。例如：
```
<GenerateDocumentationFile>true</GenerateDocumentationFile>
```
如需詳細資訊，請參閱 GenerateDocumentationFile 屬性。
如果您要使用 Visual Studio 開發應用程式，請以滑鼠右鍵按一下專案，然後選取 [[屬性]。在 [屬性] 對話框中，選取 [建置] 索引標籤，然後檢查 XML 文件檔案。您也可以變更編譯程式寫入檔案的位置。

有兩種方式可以撰寫 XML 檔批註：使用和不含 XML 標籤。兩者都使用三斜線註解。

不含 XML 標籤的批註

如果 /// 批注不是以 <開頭，則會將整個批註文字視為緊接在後面之程式代碼建構的摘要檔。當您只想為每個建構撰寫簡短摘要時，請使用此方法。

批註會在文件準備期間編碼至 XML 格式，因此不需要跳脫 <、>和 & 等字元。如果您未明確指定摘要標記，則不應該指定其他標籤，例如參數或傳回標記。

下列範例顯示替代方法，不含 XML 標籤。在此範例中，批注中的整個文字會被視為摘要。

/// Creates a new string whose characters are the result of applying
/// the function mapping to each of the characters of the input string
/// and concatenating the resulting strings.
val collect : (char -> string) -> string -> string

具有 XML 標籤的批註

如果批註本文以 < 開頭（通常是 <summary>），則會使用 XML 標籤將它視為 XML 格式化的批註本文。第二種方式可讓您指定簡短摘要、其他備註、每個參數、型別參數的文件、擲回的例外狀況，以及傳回值的說明。

以下是簽章檔中的一般 XML 文件註釋：

/// <summary>Builds a new string whose characters are the results of applying the function <c>mapping</c>
/// to each of the characters of the input string and concatenating the resulting
/// strings.</summary>
/// <param name="mapping">The function to produce a string from each character of the input string.</param>
///<param name="str">The input string.</param>
///<returns>The concatenated string.</returns>
///<exception cref="System.ArgumentNullException">Thrown when the input string is null.</exception>
val collect : (char -> string) -> string -> string

建議的標籤

如果您使用 XML 標記，下表描述 F# XML 程式代碼批註中所辨識的外部標記。

標記語法	描述
`<summary>` 文字`</summary>`	指定文字是程式項目的簡短描述。描述通常是一或兩個句子。
`<remarks>` 文字`</remarks>`	指定文字包含程式元素的補充資訊。
`<param name="` 名稱`">`描述`</param>`	指定函式或方法參數的名稱和描述。
`<typeparam name="` 名稱`">`描述`</typeparam>`	指定類型參數的名稱和描述。
`<returns>` 文字`</returns>`	指定文字用於描述函數或方法的返回值。
`<exception cref="` 類型`">`描述`</exception>`	指定可以產生的例外類型，以及在何種情況下會擲回該例外。
`<seealso cref="` 參考`"/>`	指定「另請參閱」連結以參考其他類型的文件。參考是 XML 檔案檔中顯示的名稱。另請參閱通常出現在文件頁面底部的連結。

下表描述用於描述區段內的標籤：

標記語法	描述
`<para>` 文字`</para>`	指定一段文字。這可用來分隔批註標記內的文字。
`<code>` 文字`</code>`	指定文字是多行程序代碼。文件產生器可以使用此標籤，以適合程式代碼的字型顯示文字。
`<paramref name="` 名稱`"/>`	在相同的文件註釋中指定參數的參考。
`<typeparamref name="` 名稱`"/>`	在相同文件註釋中指定類別參數的引用。
`<c>` 文字`</c>`	指定的文字為內嵌程式碼。文件產生器可以使用此標籤，以適合程式代碼的字型顯示文字。
`<see cref="` 參考`">`文字`</see>`	指定另一個程式元素的內嵌連結。參考是 XML 檔案檔中顯示的名稱。文字是連結中顯示的文字。

使用者定義的標籤

上述標籤代表 F# 編譯程式和一般 F# 編輯器工具所辨識的標籤。不過，使用者可以自由定義自己的標籤。 fsdocs 之類的工具可支援額外的標籤，例如 <namespacedoc>。自訂或內部文件產生工具也可以與標準標籤搭配使用，並支援從 HTML 到 PDF 的多個輸出格式。

編譯時間檢查

啟用 --warnon:3390 時，編譯程式會驗證 XML 的語法，以及 <param> 和 <paramref> 標記中所參考的參數。

F# 結構的記錄範例

F# 的建構如模組、成員、聯集案例和記錄欄位等會在宣告前立即由 /// 註解說明。如有需要，會藉由在自變數清單之前提供 /// 批注來記錄類別的隱含建構函式。例如：

/// This is the type
type SomeType
      /// This is the implicit constructor
      (a: int, b: int) =

    /// This is the member
    member _.Sum() = a + b

局限性

F# 不支援 C# 和其他 .NET 語言的 XML 檔某些功能。

在 F# 中，交叉參考必須使用對應符號的完整 XML 簽章，例如 cref="T:System.Console"。簡單的 C# 風格交叉參考，例如 cref="Console"，不會被詳細展開為完整的 XML 簽章，F# 編譯器也不會檢查這些元素。某些文檔工具可能允許後續處理使用這些交叉引用，但應該使用完整的簽名。
F# 編譯程式不支援標記 <include>、<inheritdoc>。如果使用它們，不會出現任何錯誤，但它們會被直接複製到生成的文件檔案中，而不會影響生成的文件。
即使使用 -warnon:3390，F# 編譯程式也不會檢查交叉參考。
F# 編譯程式不會檢查標籤 <typeparam> 和 <typeparamref> 中使用的名稱，即使使用 --warnon:3390 也是如此。
如果文件遺失，即使使用 --warnon:3390，也不會提供任何警告。

建議

基於許多原因，建議記錄程序代碼。以下是一些最佳做法、一般使用案例，以及您在 F# 程式代碼中使用 XML 檔標籤時應該知道的事項。

啟用程式代碼中的選項 --warnon:3390，以協助確保您的 XML 檔是有效的 XML。
請考慮新增簽章檔案，以分隔長 XML 檔批注與實作。
為了保持一致性，應該記錄所有公開可見的類型及其成員。如果您必須這麼做，請全部完成。
至少，模組、類型及其成員應該有一個簡單的 /// 批註或 <summary> 標籤。這會在 F# 編輯工具的自動完成工具提示視窗中顯示。
文件內容應該使用完整的句子撰寫，並以句號結尾。

共用方式為