你了解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时尤为明显。而且,规范的代码结构可以提高自己的代码质量,还可以给他人留下严谨负责的好印象。

你可能感兴趣的:(你了解C#中的XML注释吗)