XML 文档 (F#)

在 F# 中，可以利用三斜杠 (///) 代码注释生成文档。 在代码文件 (.fs) 或签名文件 (.fsi) 中，XML 注释可以位于声明之前。

利用注释生成文档

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="名称"> 描述 </param>	指定函数或方法参数的名称和描述。
<typeparam name="名称"> 描述 </typeparam>	指定类型参数的名称和描述。
<returns> text </returns>	指定 text 描述函数或方法的返回值。
<exception cref="类型"> 描述 </exception>	指定可生成的异常的类型以及引发该异常的环境。
<see cref="引用"> 文本 </see>	指定到另一个程序元素的内联链接。 reference 为 XML 文档文件中显示的名称。 text 为链接中显示的文本。
<seealso cref=" 引用"/>	指定到另一个类型的文档的“请参见”链接。 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

请参见

其他资源

F# 语言参考

编译器选项 (F#)