C# XML 注释类型参考

在 C# 中，XML 注释是一种特殊的注释类型，它可以用来对代码中的成员和类型进行标记和说明，以便在编写和使用代码时提供更好的文档和提示。XML 注释会被编译器自动提取并生成 XML 文档，可以通过 Visual Studio 中的 IntelliSense 或外部文档工具进行呈现和浏览。本文将介绍 C# 中常用的 XML 注释类型和用法。

基本格式

XML 注释以 /// 开头，后跟一行或多行文字。每行文字可以使用标记标记，标记以 < 开头，以 > 结尾。标记可以嵌套使用，但不能交叉使用。最后一行文字可以省略，但通常用于表示返回值的说明。

/// <summary>
/// 该类表示一个人的基本信息。
/// </summary>
public class Person
{
    /// <summary>
    /// 姓名。
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// 年龄。
    /// </summary>
    public int Age { get; set; }

    /// <summary>
    /// 获取该人的说明文字。
    /// </summary>
    /// <returns>该人的说明文字。</returns>
    public string GetDescription()
    {
        return $"我叫{Name}，今年{Age}岁。";
    }
}

常用标记类型

<summary> 标记用于对类型、成员或命名空间进行总体说明，一般位于注释的开头位置。<summary> 标记中的文字通常是该成员的摘要信息。一个类型、成员或命名空间只能有一个 <summary> 注释，多个 <summary> 注释会被自动合并。

<param> 标记用于对方法或属性中的参数进行说明。<param> 标记必须紧随在方法或属性定义后，具有以下格式：

/// <param name="参数名">参数说明</param>

其中，参数名 代表要说明的参数名称，参数说明 代表对该参数的详细描述。

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

<returns> 标记用于对方法、索引器或属性的返回值进行说明，通常紧随在 <param> 标记之后。如果没有返回值，则无需使用 <returns> 标记。<returns> 标记必须紧随在方法、索引器或属性定义后，具有以下格式：

/// <returns>返回值说明</returns>

其中，返回值说明 代表对返回值的详细描述。

/// <summary>
/// 计算两个数的差。
/// </summary>
/// <param name="x">第一个数。</param>
/// <param name="y">第二个数。</param>
/// <returns>两个数的差。</returns>
public int Subtract(int x, int y)
{
    return x - y;
}

<exception> 标记用于对方法或属性可能抛出的异常进行说明。<exception> 标记可以有多个，用于说明可能抛出不同类型的异常。<exception> 标记必须紧随在 <returns> 标记之后，具有以下格式：

/// <exception cref="异常类型">异常说明</exception>

其中，异常类型 表示可能抛出的异常类型，异常说明 表示对异常的详细描述。

/// <summary>
/// 将字符串转换为整数。
/// </summary>
/// <param name="s">要转换的字符串。</param>
/// <returns>转换后的整数。</returns>
/// <exception cref="System.FormatException">s 不是有效的数字字符串。</exception>
public int Parse(string s)
{
    return int.Parse(s);
}

<remarks> 标记用于对方法、属性或其他成员进行其他说明，通常位于 <returns> 或 <exception> 标记之后。<remarks> 标记中可以写任意文本，用于提供更详细的解释和备注。

/// <summary>
/// 该类表示一个点的坐标。
/// </summary>
/// <remarks>
/// 该类包括两个属性：X 和 Y，分别表示该点在水平和垂直方向上的坐标。
/// </remarks>
public class Point
{
    /// <summary>
    /// 该点在水平方向上的坐标。
    /// </summary>
    public int X { get; set; }

    /// <summary>
    /// 该点在垂直方向上的坐标。
    /// </summary>
    public int Y { get; set; }
}

自定义 XML 标记

除了上述介绍的标记类型之外，C# 还支持自定义 XML 标记，以便在注释中添加自己的标记类型，用于自定义的文档生成和解释。自定义 XML 标记的格式与内置标记相同，但需要自己定义标记名称、属性、意义和解释方式。

/// <summary>
/// 该类表示一个学生的信息。
/// </summary>
/// <remarks>
/// 该类包含两个自定义标记：<studentID>和<email>，
/// 分别用于记录学生的学号和电子邮件地址。
/// </remarks>
public class Student
{
    /// <summary>
    /// 学生的姓名。
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// 学生的年龄。
    /// </summary>
    public int Age { get; set; }

    /// <studentID>
    /// 学生的学号。
    /// </studentID>
    public string StudentID { get; set; }

    /// <email>
    /// 学生的电子邮件地址。
    /// </email>
    public string Email { get; set; }

    /// <summary>
    /// 获取该学生的说明文字。
    /// </summary>
    /// <returns>该学生的说明文字。</returns>
    public string GetDescription()
    {
        return $"我叫{Name}，今年{Age}岁，学号是{StudentID}，邮箱是{Email}。";
    }
}

结论

XML 注释是 C# 中一种很好的注释类型，它可以提供更好的代码文档和提示，方便程序员编写和使用代码。在编写 XML 注释时，要使用合适的标记类型和格式，注意语法和格式的规范，并尽量添加自定义标记用于提供更有用的信息和解释。