关于C#的Summary注释

· 2025-04-07 ·

在 C# 里，/// 形式的 summary 注释是一种 XML 注释，主要用于为代码元素（像类、方法、属性等）添加文档说明。这些注释能被 Visual Studio 等开发工具识别，还能借助工具生成外部文档。

为类添加 `summary` 注释

为类添加 summary 注释时，要在类定义的上方添加 /// <summary> 和 /// </summary> 标签，在这两个标签中间写上对类的描述。

/// <summary>
/// 这是一个代表用户的类，包含用户的基本信息和操作方法。
/// </summary>
public class User
{
    // 类的成员
}

为方法添加 `summary` 注释

为方法添加 summary 注释时，除了使用 summary 标签描述方法的功能外，还能使用 param 标签描述方法的参数，用 returns 标签描述方法的返回值。

/// <summary>
/// 计算两个整数的和。
/// </summary>
/// <param name="a">第一个整数。</param>
/// <param name="b">第二个整数。</param>
/// <returns>两个整数的和。</returns>
public int Add(int a, int b)
{
    return a + b;
}

为属性添加 `summary` 注释

为属性添加 summary 注释时，只需使用 summary 标签描述属性的用途。

/// <summary>
/// 获取或设置用户的姓名。
/// </summary>
public string Name { get; set; }

为字段添加 `summary` 注释

为字段添加 summary 注释的方式和为属性添加注释类似，用 summary 标签描述字段的用途。

/// <summary>
/// 存储用户的年龄。
/// </summary>
private int age;

生成文档

Visual Studio等开发工具能根据这些XML注释生成外部文档。要生成文档，可按以下步骤操作：

右键单击项目，选择“属性”。
在“生成”选项卡中，勾选“XML文档文件”。
构建项目，这样就会生成一个XML文件，其中包含了所有的XML注释。

查看注释提示

在Visual Studio里，当你使用带有 summary 注释的代码元素时，将鼠标悬停在该元素上，就会显示出注释内容，这有助于你快速了解代码的功能和使用方法。

在C#的XML注释里，除了常用的 <summary>、<param>、<returns> 和 <para> 标签外，还有许多其他特殊标签，它们能为代码元素提供更详细的文档说明。下面为你介绍一些常见的特殊标签及其用法：

`<remarks>`

用于为代码元素提供额外的详细说明，可补充 <summary> 未涵盖的信息。

/// <summary>
/// 计算两个整数的和。
/// </summary>
/// <remarks>
/// 此方法使用简单的加法运算来计算两个整数的和。
/// 它没有处理整数溢出的情况，在使用时需要注意。
/// </remarks>
/// <param name="a">第一个整数。</param>
/// <param name="b">第二个整数。</param>
/// <returns>两个整数的和。</returns>
public int Add(int a, int b)
{
    return a + b;
}

`<example>`

用于提供代码元素的使用示例，帮助其他开发者更好地理解如何使用该代码元素。

/// <summary>
/// 计算两个整数的和。
/// </summary>
/// <example>
/// 以下是如何使用 <see cref="Add"/> 方法的示例：
/// <code>
/// int result = Add(3, 5);
/// Console.WriteLine(result); // 输出 8
/// </code>
/// </example>
/// <param name="a">第一个整数。</param>
/// <param name="b">第二个整数。</param>
/// <returns>两个整数的和。</returns>
public int Add(int a, int b)
{
    return a + b;
}

`<see>` 和 `<seealso>`

<see>：用于在注释中创建对其他代码元素的引用，当鼠标悬停在引用上时，会显示被引用元素的摘要信息。
<seealso>：用于在生成的文档中添加一个“另请参阅”部分，列出相关的代码元素。

/// <summary>
/// 计算两个整数的和。
/// </summary>
/// <param name="a">第一个整数。</param>
/// <param name="b">第二个整数。</param>
/// <returns>两个整数的和。</returns>
/// <seealso cref="Subtract"/>
public int Add(int a, int b)
{
    return a + b;
}

/// <summary>
/// 计算两个整数的差。
/// </summary>
/// <param name="a">被减数。</param>
/// <param name="b">减数。</param>
/// <returns>两个整数的差。</returns>
public int Subtract(int a, int b)
{
    return a - b;
}

`<exception>`

用于描述方法可能抛出的异常及其抛出条件。

/// <summary>
/// 除法运算。
/// </summary>
/// <param name="a">被除数。</param>
/// <param name="b">除数。</param>
/// <returns>两个数的商。</returns>
/// <exception cref="System.DivideByZeroException">当除数为零时抛出该异常。</exception>
public double Divide(double a, double b)
{
    if (b == 0)
    {
        throw new DivideByZeroException();
    }
    return a / b;
}

`<value>`

主要用于属性的注释，描述属性的值的含义或用途。

/// <summary>
/// 获取或设置用户的年龄。
/// </summary>
/// <value>用户的年龄，必须为非负整数。</value>
public int Age { get; set; }