插入用于生成文档的 XML 注释

本文介绍如何通过自动生成标准 XML 文档注释结构来帮助记录代码元素（如类和方法）。 在编译时，可以生成包含文档注释的 XML 文件。

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

启用文档生成

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

如果使用 DocumentationFile 本身或 GenerateDocumentationFile 属性设置为 true，则会生成具有指定名称和位置的文档文件。 但是，如果设置为GenerateDocumentationFilefalse，则即使设置了该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++）
• 代码生成