zoukankan      html  css  js  c++  java
  • C#注释及说明

    做了这么多年的C#开发,针对它的完整注释都没有好好的了解过,有点悲哀啊~

    下面是转载的C# 注释及说明文章

    为了使用C#提供的XML注释功能,你的注释应该使用特殊的注释语法(///)开头。在///之后,你可以使用预先定义的标签注释你的代码,也可以插入你自己定义的标签。你定制的标签将会在随后加入到生成的注释文档中。

     

    预定义的标签               用处

    <c>                            将说明中的文本标记为代码

    <code>                      提供了一种将多行指示为代码的方法

    <example>                指定使用方法或其他库成员的示例

    <exception>              允许你指定可能发生的异常类

    <include>                  允许你引用描述源代码中类型和成员的另一文件中的注释, 使用 XML                                         XPath 语法来描述你的源代码中的类型和成员。

    <list>                         XML注释文档中插入一个列表

    <para>                      XML注释文档中插入一个段落

    <param>                  描述一个参数

    <paramref>              提供了一种指示一个词为参数的方法

    <permission>            允许你将成员的访问许可加入到文档中

    <remarks>                用于添加有关某个类型的信息

    <returns>                 描述返回值

    <see>                       指定链接

    <seealso>                指定希望在请参见一节中出现的文本

    <summary>              类型或类型成员的通用描述

    <value>                    描述属性

     





    =============================================================


    <Summary> 对整体进行概要性描述
    <summary>Description</summary>
    类、属性(不推荐)、方法等


    <para> 跟在Summary之后,对方法所涉及的入口参数进行有效的解释
    <param name=username>本参数是用户的帐号</param>
    方法的入口参数;


    <returns> 对方法的返回值进行解释;
    <returns>返回值零代表操作成功,-1代表操作不成功</returns>
    方法的返回值;


    <remarks> 对一些语句进行备注性描述
    <remarks>本类需要调用另外一个User类相关方法</remarks>
    类、方法、属性等;


    <see> 在生成的文档中产生一个连接到其它描述的超链接;
    <see cref=”[member]”/>
    可以在其它注释标识符中加入


    <seealso> 与上者的区别是本标识符显示超链接在一个文档的尾部的“See Also”区域,而前者在文档之中;
    <seealso cref=”[member]”/>
    不可以在其它注释标识符中加入


    <value> 对一个属性进行概要性解释;
    <value>这是一个public属性</value>
    属性


    <code> 如果需要置入一部分源代码段,可以使用本标识符将其标记出来
    <code>
    public int add(int a,b)
    {return a+b;
    }
    </code>
    可以在其它注释标识符中加入


    <exception> 对程序中可能抛出的异常做解释;
    <exception cref=”System.Exception”>抛出的异常情况</exception>
    在方法当中如果有抛出异常,如“try…catch结构”时可以使用本标识符做解释


    <permission> 对方法的访问权限做一些解释:
    <permission cref=”System.Security.PermissionSet”>这是公共方法</permission>
    方法,属性


    <c> 与<code>标识符基本相同,但本标识符仅用于单行代码;
    <c>return a+b;</c>
    可以在其它标识符中插入使用;


    <example> 举例说明,通常与<code>配套使用;
    <example> 以下示例说明如何调用Add方法:
    <code>
    class MyClass
    {
      public static int Main()
    {
    return Add(1+2);
    }
    }
    </code>
    </example>
    可以在其它标识符中插入;


    <paramref> 在其它地方引用一个入口参数
    <paramref cref=”a”>请注意,这是一个整型参数</paramref>

    ----------------------------------------------------------------------------------

    [csharp] view plaincopy
    1. using System;  
    2. /// <summary>  
    3. /// ClassName:SomeClass  
    4. /// Version:1.0  
    5. /// Date:2001/6/21  
    6. /// Author:cniter  
    7. /// </summary>  
    8. /// <remarks>  
    9. /// 本类仅是一个示例教学类,不完成具体的工作  
    10. /// </remarks>  
    11. public class SomeClass  
    12. {  
    13.      /// <summary>  
    14.      /// 内部私有变量,存储名称</summary>  
    15.     private string myName = null;  
    16.      public SomeClass()  
    17.      {  
    18.          //  
    19.          // TODO: Add Constructor Logic here  
    20.          //  
    21.      }  
    22.      
    23.     /// <summary>  
    24.     /// 名称属性 </summary>  
    25.     /// <value>  
    26.     ///本属性为只读属性,返回用户名</value>  
    27.     public string Name  
    28.     {  
    29.        get  
    30.        {  
    31.           if ( myName == null )  
    32.           {  
    33.              throw new Exception("Name is null");  
    34.           }  
    35.                
    36.           return myName;  
    37.        }  
    38.     }  
    39.     /// <summary>  
    40.     /// 本方法是没有进行具体构建</summary>  
    41.     /// <param name="s"> 入口参数S是一个String类型</param>  
    42.     /// <seealso cref="String">  
    43.     ///String类型的信息</seealso>  
    44.     public void SomeMethod(string s)  
    45.     {  
    46.     }  
    47.     /// <summary>  
    48.     /// 本方法仍然没有进行具体构建</summary>  
    49.     /// <returns>  
    50.     /// 返回值始终为0.</returns>  
    51.     /// <seealso cref="SomeMethod(string)">  
    52.     /// 参看SomeMethod(string)方法的说明 </seealso>  
    53.     public int SomeOtherMethod()  
    54.     {  
    55.        return 0;  
    56.     }  
    57.     /// <summary>  
    58.      /// 该应用程序的入口  
    59.     /// </summary>  
    60.     /// <param name="args"> 入口参数集合</param>  
    61.      public static int Main(String[] args)  
    62.      {  
    63.          //  
    64.          // TODO: Add code to start application here  
    65.          //  
    66.          return 0;  
    67.      }  
    68. }  
  • 相关阅读:
    使用 Spring data redis 结合 Spring cache 缓存数据配置
    Spring Web Flow 笔记
    Linux 定时实行一次任务命令
    css js 优化工具
    arch Failed to load module "intel"
    go 冒泡排序
    go (break goto continue)
    VirtualBox,Kernel driver not installed (rc=-1908)
    go运算符
    go iota
  • 原文地址:https://www.cnblogs.com/sparkleDai/p/7604964.html
Copyright © 2011-2022 走看看