XML 文件 (F#)
您可以透過 F# 中的三個斜線 (///) 程式碼註解產生文件。 XML 註解可以位在程式碼檔 (.fs) 或簽章檔 (.fsi) 的宣告前面。
從註解產生文件
F# 中從註解產生文件的支援與其他 .NET Framework 語言中的支援相同。 如同其他 .NET Framework 語言，-doc 編譯器選項可讓您產生包含資訊的 XML 檔案，而此資訊可透過 Sandcastle 這類工具轉換為文件。 使用工具 (設計與以其他 .NET Framework 語言撰寫的組件搭配使用) 所產生的文件，一般會產生根據 F# 建構之已編譯形式的 API 檢視。 除非工具特別支援 F#，否則這些工具所產生的文件不會符合 API 的 F# 檢視。
如需如何透過 XML 產生文件的詳細資訊，請參閱 XML 文件註解 (C# 程式設計手冊)。
建議的標記
有兩種方式可以撰寫 XML 文件註解。 其中一種是直接以三個斜線註解來撰寫文件，而不使用 XML 標記。 如果您這麼做，則會將整個註解文字當成緊接之程式碼建構的摘要文件。 只有在想要撰寫每個建構的簡短摘要時，才使用這個方法。 另一種方法是使用 XML 標記來提供較具結構化的文件。 第二種方法可讓您指定簡短摘要、其他備註、每個參數和型別參數的文件及擲回的例外狀況，以及傳回值描述的個別附註。 下表描述可在 F# XML 程式碼註解中辨識的 XML 標記。
標記語法 |
描述 |
|---|---|
<c> text </c> |
指定 text 是程式碼。 文件產生器可以使用這個標記，以程式碼適用的字型來顯示文字。 |
<summary> text </summary> |
指定 text 是程式項目的簡短描述。 這個描述通常是一個或兩個句子。 |
<remarks> text </remarks> |
指定 text 包含程式項目的補充資訊。 |
<param name="name"> description </param> |
指定函式或方法參數的名稱和描述。 |
<typeparam name="name"> description </typeparam> |
指定型別參數的名稱和描述。 |
<returns> text </returns> |
指定 text 描述函式或方法的傳回值。 |
<exception cref="type"> description </exception> |
指定可以產生的例外狀況型別以及擲出該例外狀況的情況。 |
<see cref="reference"> text </see> |
指定到另一個程式項目的內嵌連結。 reference 是顯示於 XML 文件檔的名稱。 text 是連結中顯示的文字。 |
<seealso cref="reference"/> |
指定到另一種型別之文件的＜請參閱＞連結。 reference 是顯示於 XML 文件檔的名稱。 ＜請參閱＞連結通常出現在文件頁面的底端。 |
<para> text </para> |
指定文字段落。 這是用來區隔 remarks 標記內的文字。 |
範例
描述
下列是簽章檔中的一般 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 標記的替代方法。 在此範例中，註解中的整個文字都視為摘要。 請注意，如果您未明確指定摘要標記，則不應該指定其他標記 (例如 param 或 returns 標記)。
程式碼
/// 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