你了解C#中的XML注释吗

XML注释是什么

在VS中编写C#代码时，如果在类、变量、方法等上方连续输入三个“/”，VS会自动为我们生成一段XML注释模板。通过这段模板，我们可以将代码的注释规范化，形成一份XML注释文档（可以在项目“生成”设置中对保存路径进行配置）。这样，不仅VS可以读取，还可以让如Swagger等第三方插件使用。

以下代码展示了常用的文档标记：

/// <summary>
/// 动物工厂
/// </summary>
public class AnimalFactory
{
    /// <summary>
    /// 创建类型为 <typeparamref name="TAnimal"/> 的动物
    /// </summary>
    /// <typeparam name="TAnimal">动物的类型</typeparam>
    /// <param name="name">动物的名字</param>
    /// <returns>一个继承于 <see cref="Animal"/> 抽象类的实体</returns>
    /// <exception cref="ArgumentException">当 <paramref name="name"/> 为 <c>null</c>、<c>""</c> 或空白字符串时抛出</exception>
    /// <example>
    /// 你可以通过如下方式创建 <see cref="Dog"/> 的实例
    /// <code>
    /// var dog = AnimalFactory.CreateAnimal{Dog}(“小白”);
    /// Console.WriteLine(dog.Name);
    /// </code>
    /// </example>        
    /// <remarks><see cref="CreateAnimal{TAnimal}(string)"/> 是 <c>AnimalFactory</c> 的静态方法</remarks>
    public static TAnimal CreateAnimal<TAnimal>(string name) where TAnimal : Animal, new()
    {
        if (string.IsNullOrWhiteSpace(name))
            throw new ArgumentException("动物名字不能为空", nameof(name));

        return new TAnimal()
        {
            Name = name
        };
    }
}

/// <summary>
/// 动物
/// </summary>
public abstract class Animal
{
    private string _name;

    /// <summary>
    /// 名字
    /// </summary>
    /// <value>Name属性 get/set 的值是字符串字段：_name</value>
    public string Name
    {
        get => _name;
        set => _name = value;
    }
}

/// <summary>
/// 狗
/// </summary>
public class Dog : Animal
{

}

将dll与xml提供给他人使用时，VS中看到的就是这样：

//
// 摘要:
//     动物工厂
public class AnimalFactory
{
    public AnimalFactory();

    //
    // 摘要:
    //     创建类型为 TAnimal 的动物
    //
    // 参数:
    //   name:
    //     动物的名字
    //
    // 类型参数:
    //   TAnimal:
    //     动物的类型
    //
    // 返回结果:
    //     一个继承于 ConsoleAppForXML.Animal 抽象类的实体
    //
    // 异常:
    //   T:System.ArgumentException:
    //     当 name 为 null、"" 或空白字符串时抛出
    //
    // 言论：
    //     ConsoleAppForXML.AnimalFactory.CreateAnimal``1(System.String) 是 AnimalFactory
    //     的静态方法
    public static TAnimal CreateAnimal<TAnimal>(string name) where TAnimal : Animal, new();
}

XML文档标记

• <summary></summary>：描述标注的类型或成员信息
• <typeparam name=""></typeparam>：描述泛型类型的信息
  • name：泛型类型的名称
• <typeparamref name=""/>：按住“Ctrl”键可以导航到该泛型类型
  • name：泛型类型的名称
• <param name=""></param>：描述方法参数
  • name：参数的名称
• <paramref name="name"/>：按住“Ctrl”键可以导航到该参数
  • name：参数的名称
• <returns></returns>：描述方法返回值
• <see cref=""/> ：按住“Ctrl”键可以导航到该标记（如类、变量等）
  • cref：标记名称
• <exception cref=""></exception>：描述方法内可能抛出的异常类型
  • cref：异常类型
• <c></c>：标记其中的内容为代码，并且只有一行
• <code></code>：标记其中的内容为代码，可以有多行
• <example></example>：提供使用该成员的示例代码，通常与<code></code>一起使用
• <remarks></remarks>：提供更多备注信息
• <value></value>：指示属性 get/set 操作的字段

个人认为，规范的XML注释文档在项目开发和维护时可以起到事半功倍的作用，尤其是对外提供API时尤为明显。而且，规范的代码结构可以提高自己的代码质量，还可以给他人留下严谨负责的好印象。