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

  • 相关阅读:
    Eclipse解决Ctrl+c很卡的方法
    关于编程,大学没有传授的十件事-月光博客
    最牛B的编码套路
    (CareerCup)find the largest repetitive sequence
    (CareerCup)Find next higher number with same digits
    2013年HTML5峰会 一场守望者的盛宴
    Youzi2D推出开源HTML5游戏加速引擎
    HTML5与原生APP之争胜负已出?
    编程的未来
    拖拽即可创建HTML5网站的建站平台
  • 原文地址:https://www.cnblogs.com/xiaoxiaotank/p/12116419.html
Copyright © 2011-2022 走看看