现在的位置: 首页 > 综合 > 正文

C#注释与XML文档说明

2013年10月10日 ⁄ 综合 ⁄ 共 897字 ⁄ 字号 评论关闭

C#使用传统的C风格的注释方式,即:

  •     单行注释:// ...
  •     多行注释:/ * ... * /

    除了C风格的注释外,C#还可以根据特定的注释自动创建XML格式的文档说明。这些注释都是单行注释,但都以3个斜杠 /// 开头,而不是通常的两个斜杠。在这些注释中,可以把包含类型和类型成员的文档说明的XML标识符放在代码中。

编译器可以识别的标识符如下:

 

标识符  说明 
<c>  把行中的文本标记为代码,例如:<c>int i=10;</c> 
<code>  把多行标记为代码 
<example>  标记为一个代码示例 
<exception>  说明一个异常类(编译器要验证其语法) 
<include>  包含其他文档说明文件的注释(编译器要验证其语法) 
<list> 把列表插入到文档说明中 
<param>  标记方法的参数(编译器要验证其语法) 
<paramref>  表示一个单词是方法的参数(编译器要验证其语法) 
<permission>  说明对成员的访问(编译器要验证其语法) 
<remarks>  给成员添加描述 
<returns>  说明方法的返回值 
<see>  提供对另一个参数的交叉引用(编译器要验证其语法) 
<seealso>  提供描述中的“参见” 部分(编译器要验证其语法)
<summary>  提供类型或成员的简短小结 
<value>  描述属性 

 

 

    C#编译器可以把XML元素从特定的注释中提取出来,并使用它们生成一个XML文件,要让编译器为程序集生成XML文档说明,需在编译时指定/doc选项,其后需跟上要被创建的文件的名称:

    csc /t:library /doc:MathLib.xml MathLib.cs

    如果XML注释没有生成格式正确的XML文档,编译器就抛出一个错误。

注意:

    编译器创建了一个<assembly>元素,并为该文件中的每个类或类成员添加一个<member>元素。每个<member>元素都有一个name特性,其中包含成员的全名,前面有一个字母表示其类型:

    “T:”--表示这是一个类型;

    “F:”--表示这是一个字段;

    “M:”--表示这是一个成员

抱歉!评论已关闭.