为文档生成插入 XML 注释

本文说明了 Visual Studio 如何通过自动生成标准的 XML 文档注释结构，来帮助记录类和方法等文档代码元素。 在编译时，可生成一个包含文档注释的 XML 文件。

可将由编译器生成的 XML 文件与 .NET 程序集一起分发，让 Visual Studio 和其他 IDE 能够使用 IntelliSense 快速显示类型和成员信息。 还可以通过 DocFX 和 Sandcastle 等工具运行 XML 文件，从而生成 API 参考网站。

注意

C# 和 Visual Basic 中提供了可自动插入 XML 文档注释结构的 Insert Comment 命令。 在 C++ 中，可以手动插入 XML 文档注释，并且仍可在编译时生成 XML 文档文件。

启用文档生成

要启用文档生成，请在项目属性的“生成”>“输出”选项卡上选择“生成包含 API 文档的文件”复选框。

默认情况下，将在程序集所在目录中生成一个名称与程序集相同的文档文件，文件扩展名为 .xml。 如果要为该文件配置非默认名称或位置，请在“XML 文档文件路径”下相应输入或浏览到备用位置。

也可以将GenerateDocumentationFile 或 DocumentationFile 属性添加到 .csproj、.vbproj 或 .fsproj 文件。 将 GenerateDocumentationFile 设置为 true，以生成具有默认名称和位置的文档文件。 使用 DocumentationFile 属性指定其他名称或位置。

如果使用 DocumentationFile 本身或将 GenerateDocumentationFile 属性设置为 true，则会生成具有指定名称和位置的文档文件。 但如果将 GenerateDocumentationFile 设置为 false，则即使设置了 DocumentationFile 属性，也不会生成任何文档文件。

启用注释插入键盘快捷方式

在 C# 中键入 /// 或在 Visual Basic 中键入 ''' 后，可以设置注释选项以自动插入 XML 注释结构。

1. 从 Visual Studio 菜单栏，选择“工具”>“选项”。
2. 在“选项”对话框中，导航到“文本编辑器”>“C#”（或“Visual Basic”）>“高级”。
3. 在“注释”部分下，选择或取消选择“为 \\\ 生成 XML 文档注释”（或“'''”）。

自动插入 XML 注释

1. 在 Visual Studio 中，将游标放在要记录的元素上（例如，一种方法）。

2. 请执行以下一项操作：

   • 如果启用了自动注释插入快捷方式，请在 C# 中键入 /// 或在 Visual Basic 中键入 '''。
   • 在“编辑”菜单上，选择“IntelliSense”>“插入注释”。
   • 在右键单击或关联菜单中，选择“片段”>“插入注释”。

   这时会立即基于代码元素生成 XML 注释结构。 例如，在注释 GetUserName 方法时，该模板会生成 <summary> 元素，为该参数生成一个 <param> 元素，并生成一个记录返回值的 <returns> 元素。

   /// <summary>
   /// 
   /// </summary>
   /// <param name="id"></param>
   /// <returns></returns>
   public string GetUserName(int id)
   {
       return "username";
   }
   

   ''' <summary>
   ''' 
   ''' </summary>
   ''' <param name="id"></param>
   ''' <returns></returns>
   Public Function GetUserName(id As Integer) As String
       Return "username"
   End Function
   

3. 为每个 XML 元素输入说明以完整记录代码。 例如：

    /// <summary>
    /// Gets the username associated with the specified ID.
    /// </summary>
    /// <param name="id">The unique user ID.</param>
    /// <returns>A string containing the username for the specified ID.</returns>
    public string GetUserName(int id)
    {
        return "username";
    }
   

可以在注释中使用 XML 元素和样式，从而在将鼠标悬停在代码上时在“快速信息”中呈现。 这些元素包括斜体或粗体样式、项目符号列表或编号列表，以及可点击的 cref 或 href 链接。

例如，将 C# 程序文件中输入以下代码：

/// <summary>
/// There are two <see href="https://bing.com">params</see>.
/// <list type="number">
/// <item><param name="id">The user <em>id</em></param></item>
/// <item><param name="username">The user <em>name</em></param></item>
/// </list>
/// </summary>
/// <returns>The <strong>username</strong>.</returns>
public static string GetUserName(int id)
{
    return "username";
}

将鼠标悬停在 GetUserName 上时，“快速信息”窗格将显示如下：

相关内容

• 文档注释
• 在 Visual Basic 中创建 XML 文档
• 注释 (C++)
• XML 文档 (Visual C++)
• 代码生成