使用 XML 批註記錄程式代碼

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

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

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

您可以在專案檔中啟用此警告，方法是將元素<WarnOn>新增至<PropertyGroup>區段：

<WarnOn>3390</WarnOn>

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

• 您可以將 GenerateDocumentationFile 元素新增到 <PropertyGroup> 專案檔的 .fsproj 區段，此動作會在專案目錄中產生一個 XML 檔案，其根檔名與組件相同。 例如：

  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  

  如需詳細資訊，請參閱 GenerateDocumentationFile 屬性。

• 如果您要使用 Visual Studio 開發應用程式，請以滑鼠右鍵按一下專案，然後選取 [[屬性]。 在 [屬性] 對話框中，選取 [建置] 索引標籤 ，然後檢查 XML 文件檔案。 您也可以變更編譯程式寫入檔案的位置。

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

不含 XML 標籤的批註

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

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

備註

當您使用沒有 XML 標籤的註解時，您包含的任何標記 （例如 HTML 標籤或類似 XML 的語法） 都不會由編譯器或 F# 工具剖析或檢查。 某些外部工具（例如 GitHub）可能會嘗試解析標記，但如果語法包含錯誤，它們可能會失敗。 如果您需要在文件中使用 XML 標籤，請使用適當的 XML 標籤 <summary> 包裝註解，例如確保在啟用時 --warnon:3390 由編譯器驗證。

下列範例顯示替代方法，不含 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 檔案檔中顯示的名稱。 另請參閱通常出現在文件頁面底部的連結。
<include file="path.xml" path="XPath"/>	從 F# 11 編譯器開始，會在產生的文件中包含外部檔案中選定的 XML 元素。
<inheritdoc/>	請求會繼承相容工具的文件。 標籤仍保留在編譯器產生的 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

重用與繼承文件

為了維持一次共享的評論，請將它們 shared.xml 放在你的來源旁邊：

<docs>
  <tracking>
    <remarks>An unrecognized tracking identifier has status Unknown.</remarks>
  </tracking>
</docs>

兩位成員都選擇了相同的 XPath 表達式：

/// <summary>Find the latest status of a shipment.</summary>
/// <include file="shared.xml" path="/docs/tracking/*"/>
let status trackingId =
    if trackingId = "SHP-1042" then "Dispatched" else "Unknown"

/// <summary>Find the latest statuses of several shipments.</summary>
/// <include file="shared.xml" path="/docs/tracking/*"/>
let statuses trackingIds =
    trackingIds |> List.map (fun id -> id, status id)

啟用 GenerateDocumentationFile 或通過 --doc:Tracking.xml。 從 F# 11 開始，所發出的條目包含選定的備註與局部摘要，而不僅僅是包含標籤。

範例專案追蹤 XML 作為編譯輸入，因此編輯會觸發再生。 不需要語言版本的選擇加入。 包含以生成的 XML 展開，而非即時快速資訊。

包含解析與錯誤

相對檔名會先在來源檔案的目錄中解析，接著是編譯器的工作目錄。 巢狀則包含相對於其包含的 XML 檔案的解析。 選擇 元素，例如 /docs/tracking/*，而非文字或屬性節點。

遺失檔案、格式錯誤的 XML、無效的 XPath 以及週期系統會產生診斷結果。 有效的 XPath 沒有配對，會保留標籤並在無警告的情況下新增留言。 DTD 處理與外部 XML 解析皆被停用;外國命名空間 include 元素仍屬普通內容。 請參閱 XPath 語法參考資料。<include>

工具中的繼承文件

為避免將基底成員的描述複製到每個覆寫中，請使用 <inheritdoc/>：

[<AbstractClass>]
type TrackingBase() =
    /// <summary>Find the latest status of a shipment.</summary>
    abstract Status: trackingId: string -> string

type TrackingService() =
    inherit TrackingBase()
    /// <inheritdoc/>
    override _.Status trackingId = status trackingId

F# 11 工具與 FSharp.Compiler.Service 會揭露繼承的描述。TrackingService.Status 編譯器會留下 <inheritdoc/> 已輸出的 XML 供後續工具解讀;僅僅更新 Core 並不會更新編輯器的解析器。

使用頂層<inheritdoc/>，不要在 。<summary> 明確 cref的、建構子，以及跨語言或跨組合語言的案例，則取決於文件使用者。 使用完整的 XML 文件識別碼並檢查目標工具。 請參考參考資料<inheritdoc>。

局限性

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

• 在 F# 中，交叉參考必須使用對應符號的完整 XML 簽章，例如 cref="T:System.Console"。 簡單的 C# 風格交叉參考，例如 cref="Console"，不會被詳細展開為完整的 XML 簽章，F# 編譯器也不會檢查這些元素。 某些文檔工具可能允許後續處理使用這些交叉引用，但應該使用完整的簽名。

• 在 F# 11 之前，編譯器會複製 <include> 但不會展開。 <inheritdoc> 仍需文件使用者解析繼承內容，如 Reuse and inherit documentation 所述。

• 即使使用 -warnon:3390，F# 編譯程式也不會檢查交叉參考。

• F# 編譯程式不會檢查標籤 <typeparam> 和 <typeparamref> 中使用的名稱，即使使用 --warnon:3390 也是如此。

• 如果文件遺失，即使使用 --warnon:3390，也不會提供任何警告。

建議

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

• 啟用程式代碼中的選項 --warnon:3390，以協助確保您的 XML 檔是有效的 XML。

• 請考慮新增簽章檔案，以分隔長 XML 檔批注與實作。

• 為了保持一致性，應該記錄所有公開可見的類型及其成員。 如果您必須這麼做，請全部完成。

• 至少，模組、類型及其成員應該有一個簡單的 /// 批註或 <summary> 標籤。 這會在 F# 編輯工具的自動完成工具提示視窗中顯示。

• 文件內容應該使用完整的句子撰寫，並以句號結尾。

另請參閱

• C# XML 檔批註 （C# 程式設計手冊）。
• F# 語言參考
• 編譯程序選項