使用 XML 注释记录代码

可以从 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 标记的注释

///如果注释不以 a <开头，则整个注释文本将作为紧随其后的代码构造的摘要文档。 如果只想为每个构造编写简短摘要，请使用此方法。

注释在文档准备过程中编码为 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 代码注释中识别的外部标记。

下表描述了在说明部分中使用的标记：

用户定义的标记

前面的标记表示由 F# 编译器和典型的 F# 编辑器工具识别的标记。 但用户可随意定义自己的标记。 fsdocs 等工具支持命名空间等>额外标记<。 还可以将自定义或内部文档生成工具与标准标记一起使用，并且支持从 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# 编辑工具的自动完成工具提示窗口中显示。

• 应使用句号结尾的完整句子编写文档文本。

另请参阅

• C# XML 文档注释 （C# 编程指南）。
• F# 语言参考
• 编译器选项