你了解C#中的XML注释吗

XML注释是什么

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

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

/// 

/// 动物工厂
/// 
public class AnimalFactory
{
    /// 

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

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

/// 

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

    /// 

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

/// 

/// 狗
/// 
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(string name) where TAnimal : Animal, new();
}

XML文档标记

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

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