使用 XML 註解記錄您的程式碼

發行項
03/07/2024

您可以從 F# 中的三斜線 (///) 程式碼註解產生文件。 XML 註解可以在程式碼檔案 (.fs) 或特徵標記 (.fsi) 檔案之前宣告。

XML 文件註解是一種特殊類型的註解，新增於任何使用者定義型別或成員的定義上方。 XML 文件註解具特殊性，因為編譯器可以處理它們以在編譯時期產生 XML 文件檔案。編譯器所產生的 XML 檔案可以隨著 .NET 組件一起散發，因此 IDE 可以使用工具提示來顯示型別或成員的快速資訊。此外，可以透過 fsdocs 這類工具執行 XML 檔案來產生 API 參考網站。

除非啟用下列選項來檢查註解在編譯時間的有效性和完整性，否則編譯器會忽略 XML 文件註解，就像所有其他註解一樣。

您可以執行下列其中一項動作，以在編譯時期產生 XML 檔案︰

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

撰寫 XML 文件註解的方式有兩種：含有和不含有 XML 標記。兩者都使用三斜線註解。

沒有 XML 標記的註解

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

註解會在文件準備期間編碼為 XML，因此不需要逸出 <、> 和 & 等字元。如果您未明確指定摘要標記，則不應該指定其他標記，例如 param 或 returns 標記。

下列範例顯示替代方法，不含 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>`*text*`</summary>`	指定文字是程式元素的簡短描述。描述通常是一個或兩個句子。
`<remarks>`*text*`</remarks>`	指定文字包含程式元素的相關補充資訊。
`<param name="`名稱`">`描述`</param>`	指定函式或方法參數的名稱和描述。
`<typeparam name="`名稱`">`描述`</typeparam>`	指定型別參數的名稱和描述。
`<returns>`*text*`</returns>`	指定文字描述函式或方法的傳回值。
`<exception cref="`型別`">`描述`</exception>`	指定可以產生的例外狀況型別，以及擲回例外狀況的情況。
`<seealso cref="`*reference*`"/>`	為另一種型別指定文件的 [另請參閱] 連結。參考是出現在 XML 文件檔案中的名稱。 [另請參閱] 連結通常會出現在文件頁面底部。

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

標記語法	描述
`<para>`*text*`</para>`	指定文字的段落。這可用來分隔 remarks 標記內的文字。
`<code>`*text*`</code>`	指定文字是多行程式碼。文件產生器可以使用此標記，以適用於程式碼的字型顯示文字。
`<paramref name="`*name*`"/>`	指定相同文件註解中參數的參考。
`<typeparamref name="`*name*`"/>`	指定相同文件註解中型別參數的參考。
`<c>`*text*`</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# 編譯器也不會檢查交叉參考。
在 <typeparam> 和 <typeparamref> 標記中使用名稱，而且 F# 編譯器不會檢查，即使使用 --warnon:3390 時也一樣。
如果文件遺失，不會發出任何警告，即使使用 --warnon:3390 時也一樣。

建議

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

在您的程式碼中啟用選項 --warnon:3390，以協助確保您的 XML 文件是有效的 XML。
請考慮新增特徵標記檔案，以將長 XML 文件註解與實作分開。
為保持一致性，應該記錄所有公開可見的類型和其成員。如果您必須執行它，則請執行。
模組、型別及其成員至少應該有一般 /// 註解或 <summary> 標記。這會顯示在 F# 編輯工具的自動完成工具提示視窗中。
應該使用結尾為句號的完整句子來撰寫文件文字。