c#文档注释规范.docx

《c#文档注释规范.docx》由会员分享，可在线阅读，更多相关《c#文档注释规范.docx（30页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、C#提供一种机制，使程序员可以使用含有XML文本的特殊注释语法为他们的代 码编写文档。在源代码文件中，具有某种格式的注释可用于指导某个工具根据这些 注释和它们后面的源代码元素生成XMLo使用这种语法的注释称为文档注释（documentation comment）。这些注释后面必须紧跟用户定义类型（如类、 委托或者接口）或者成员（如字段、事件、属性或者方法）。XML生成工具称作 文档生成器（documentation generator）。（此生成器可以但不一定必须是 C#编译器本身。）由文档生成器产生的输出称为文档文件（documentation file） 文档文件可作为文档查看器（docu

2、mentation viewer） 的输入；文档查看器 是用于生成类型信息及其关联文档的某种可视化显示的工 具。此规范推荐了一组在文档注释中使用的标记，但是这些标记不是必须使用的，如 果需要也可以使用其他标记，只要遵循“符合格式标准的XML”规则即可。A.I.介绍具有特殊格式的注释可用于指导某个工具根据这些注释和它们后面的源代码元 素生成XMLo这种注释是以三个斜杠（/）开始的单行注释，或者是以一个斜 杠和两个星号（/*）开始的分隔注释。这些注释后面必须紧跟它们所注释的用 户定义类型（如类、委托或者接口）或者成员（如字段、事件、属性或者方法）。 属 性节（第 错误！未找到引用源。节）被视为声明

3、的一部份，因此，文档注释必须位于应用到类型或者成员的属性之前。语法：single- line- doc- comment:/ input- charactersODtdelimited- doc- comment:/ * delimited- comment- charactersopt * /在 single-lin。-doc-comment中，如果当前 single-lin。-doc-comment旁边的 每一个 single-line-doc-comment上的 / 字符后跟有 whitespace 字符，则 此whitespace字符不包括在XML输出中。在delimited-doc-

4、comment中，如果第二行上的第一个非whitespace字符是 一个asterisk,并且在delimited-doc-comment内的每行开头都重复同一个由/ / / ltem 2./ / / public static void Main () / .) )A.2.7. 此标记用于其他标记内，如 (第 A211 .summary节)或 者 (returns (第A,2.12节)，用于将结构添加到文本中。语法：content其中content段落文本。示例:/ This is the entry point of the Point class testing program./ Th

5、is program tests each method and operator, and/ is intended to be run after any non-trvial maintenance has/ been performed on the Point class. public static void Main() / .)A.2.8. 该标记用于描述方法、构造函数或者索引器的参数。语法：descri ption其中name参数名。descri pti on参数的描述。示例：/ This method changes the points location to/ the

6、given coordinates. / the new x-coordinate./ the new y-coordinate. public void Move(int xor, int yor) X = xor;yor;A.2.9. 该标记表示某单词是一个参数。这样，生成文档文件后经适当处理，可以用某种 独特的方法来格式化该参数。语法：其中name参数名。示例：/ This constructor initializes the new Point to/ ( , ) ,/ the new Points x-coordinate./ the new Points y-coordinate

7、.public Point(int xor, 1 nt yor) X = xor;Y = yor;)A.2.10. 该标记用于将成员的安全性和可访问性记入文档。语法：description其中cref=member”成员的名称。文档生成器检查给定的代码元素是否存在，并将member转 换为文档文件中的规范化元素名称。description对成员的访问属性的说明。示例：/ Everyone can/ access this method. public static void Test() )A.2.11. 该标记用于指定类型的概述信息。(使用(summary(第A.2.15. 节) 描述类型的

8、成员。)语法：descri pti on其中description摘要文本。示例：/summaryClass Point models a point in a / two-dimensional plane. public class Point (/ . )A.2.12. 该标记用于描述方法的返回值。语法:descri pti on其中description返回值的说明。示例:/ Report a point* s location as a string./ A string represent!ng a points location, in the form (x,y),/ with

9、out any 1eading, trailing, or embeddedwhitespace. public override string ToString() return H(H + x + ”J + Y + )”；)A.2.13. 该标记用于在文本内指定链接。使用 (第A.2.14. 节)指 示将在“请参见”部份中浮现的 文本。语法:其中cref=membern成员的名称。文档生成器检查给定的代码元素是否存在，并将member更 改为所生成的文档文件中的元素名称。示例:/ This method changes the point* s location to/ the given

10、 coordinates. / public void Move(int xor, int yor) X = xor;yor;/ This method changes the point* s location by/ the given x- and y-offsets./ / public void Translate(int xor, int yor) X += xor;Y += yor;)A.2.14. 该标记用于生成将列入“请参见”部份的项。使用 (第A.2.13. 节) 指定来自文本内的链接。语法：其中cref=nmembern成员的名称。文档生成器检查给定的代码元素是否存在，并

11、将member更 改为所生成的文档文件中的元素名称。示例:/ This method determines whether two Points have the same / location./ / public override bool Equals(object o) / .)A.2.15. 可以用此标记描述类型的成员。使用 (第 1.summary节) 描述类型本身。语法：descri pti on其中description关于成员的摘要描述。示例：/ This constructor initializes the new Point to (0,0).public Point(

12、) : this(0,0) )A.2.16. 该标记用于描述属性。语法:property description其中property description属性的说明。示例：/ Property X represents the pointsx-coordinate. publi c i nt X(get return x; set x = value; )A.3.处理文档文件文档生成器为源代码中每一个附加了 “文档注释标记”的代码元素生成一个ID 字符串。该ID字符串惟一地标识源元素。文档查看器利用此ID字符串来标 识该文档所描述的对应的元数据反射项。文档文件不是源代码的层次化表现形式；而是

13、为每一个元素生成的ID字符串的 一维列表。A.3.1. ID字符串格式文档生成器在生成ID字符串时遵循下列规则: 不在字符串中放置空白。. 字符串的第一部份通过单个字符后跟一个冒号来标识被标识成员的种类。定义以下几种成员：字符说明E事件F字段M方法（包括构造函数、析构函数和运算符）N命名空间P属性（包括索引器）T类型（如类、委托、枚举、接口和结构）错误字符串；字符串的其他部份提供有关错误的信息。例 如，文档生成器对无法解析的链接生成错误信息。 字符串的第二部份是元素的彻底限定名，从命名空间的根开始。元素的 名称、包含着它的类型和命名空间都以句点分隔。如果项名本身含有句点，则将 用#（U+002

14、3）字符替换。（这里假定所有元素名中都没有“#（U+OO23）”字符。） 对于带有参数的方法和属性，接着是用括号括起来的参数列表。对于那 些不带参数的方法和属性，则省略括号。多个参数以逗号分隔。每一个参数的编 码都与CLI签名相同，如下所示：参数由其彻底限定名来表示。例如，int 变成 System. Int32 string 变成 System. String object 变成System.Object等。具有out或者ref修饰符的参数在其类型名后跟有 符。对于由值传递或者通过params传递的参数没有特殊表示法。数组参数 表示为 lowerbound ： size , . , lowe

15、rbound ： size ,其中逗号数量 等于秩减去一，而下限和每可选whitespace字符和asterisk字符组成的样式，则该重复浮现的样式所含 的字符不包括在XML输出中。此样式中，可以在asterisk字符之前或者之后 包 括 whitespace 字符。示例：/ Class Point models a point in a two-dimensional / plane./public class Point/ method draw renders the point. void draw() .)文档注释内的文本必须根据XML规则(http:www. w3. org/TR/

16、REC-xml)设置 正确的格式。如果XML不符合标准格式，将生成警告，并且文档文件将包含一 条注释，指出遇到错误。尽管开辟人员可自由创建它们自己的标记集，但第A.2.建议的标记节定义有 建议的标记集。某些建议的标记具有特殊含义： 标记用于描述参数。如果使用这样的标记，文档生成器必须 验证指定参数是否存在以及文档注释中是否描述了所有参数。如果此验证失败， 文档生成器将发出警告。 cref属性可以附加到任意标记，以提供对代码元素的参考。文档生成 器必须验证此代码元素是否存在。如果验证失败，文档生成器将发出警告。查找 在cref属性中描述的名称时，文档生成器必须根据源代码中浮现的using语 句来

17、考虑命名空间的可见性。 标记旨在标出可由文档查看器显示的有关类型或者成员的 额外信息。标记表示应该包含的来自外部XML文件的信息。个维的大小(如果已知)用十进制数表示。如果未指定下限或者大小，它将被省略。 如果省略了某个特定维的下限及大小，则“：”也将被省略。交织数组由每一个 级别一个“口”来表示。指针类型为非void的参数用类型名后面跟一个* 的形式来表示。void指针用类型名System.Void表不。A.3.2. ID字符串示例下列各个示例分别演示一段C#代码以及为每一个可以含有文档注释的源元素 生成的ID字符串：类型用它们的彻底限定名来表示。enum Color Red, Blue,

18、Green namespace Acmeinterface iProcess struct VaiueType -class widget: IProcess(public class Nestedclass public interface iMenultem public delegate void Del(int i);public enum Di recti on North, South, East, West )nT：ColorHnT:Acme ,工Process”nT: Acme . Val ueType1T:Acme.widgetT:Acme.widget.Nestedclas

19、sT：Acme . widget.IMenultemnT:Acme . widget.DelT:Acme.Widget.Di recti on字段用它们的彻底限定名来表示。namespace Acme(struct VaiueType(private int total;)class widget: iProcesspublic class NestedClass(private int value;)private string message;private static Color defaultcolor;private const double PI = 3.14159;protec

20、ted readonly double monthlyAverage;private long口 arrayl;private widget, array2;private unsafe int *pCount;private unsafe float *ppvalues;)H F:Acme VaiueType.totalnnn“ F: Acme wi dget month! yAve rage1 F:Acme wi dget arraylF：Acme.wi dget.array2”“ F:Acme. widget.pCountH F:Acme.widget.ppval ues 构造函数。na

21、mespace Acme(class Widget: iProcess(static widget() .public WidgetO . . . public Widget(string s) )nM：Acme.wi dget.#cctorHM：Acme.wi dget.#ctorM：Acme Widget.#ctor(System. String) 析构函数。namespace Acme(class widget: IProcess(-WidgetO . . . M:Acme . widget.Fi nal1zen方法。namespace Acme (struct VaiueTypepub

22、lic void M(int i) - )class widget: iProcess (public class NestedClass(public void M(int i) )public static void M0() public void Ml(char c, out float f, ref VaiueType v) -public void M2 (short xl, 1 nt , x2 , long 口口 x3) .public void M3(long x3, Widget, x4) .public unsafe void M4(char *pc, Color *pf)

23、 .public unsafe void M5(void *pv, double *， pd) public void M6(int i, params object args) ) )nM:Acme.VaiueType.M(System.Int32)M：Acme.Widget.NestedClass.M(System.Int32)“M:Acme.Widget.MO”nM：Acme . Wi dget.Ml(System.Char,System.si ngle,Acme.VaiueType)H nM：Acme.Widget.M2(System.Intl6,System.Int320:,0: ,

24、System.InUM:Acme.wi dget.M3(System.Int64,Acme.widget0:,0:,0:口)”nM:Acme.wi dget.M4(system.Char*,Color*)”MM:Acme.widget.M5(System.Vold*,System.Double*0:,0:)M：Acme.Widget.M6(System.Int32,System.object)n 属性和索引器。namespace Acme (class widget: iProcess (public int width get set - public int thisint i get s

25、et public 1 nt thisstring s, int i get set ) )“P:Acme . wi dget. widthunP：Acme.Widget.ltem(System.Int32)HHP：Acme.widget.ltem(System.String,System.Int32) 事件。namespace Acme( class Widget: IProcess (publi c event Del AnEvent;)E:Acme . widget.AnEvent一元运算符。 namespace Acme (class widget: iProcesspublic st

26、atic Widget operator+(Widget x) )nM：Acme.Widget.op_UnaryPlus(Acme.wi dget)n下面列出可使用的一元运算符函数名称的完整集合：op_unaryPlus、op_UnaryNegation、op_Logi cal Not、op_OnesComplement op_lncrement op_Decrement op.True 和 op_Fa1se。 二元运算符。namespace Acmeclass Widget: IProcesspublic static widget operator+(widget xl, widget x

27、2) -)“ M:Acme widget.op_Addition(Acme.widget,Acme.Widget)n下面列出可使用的二元运算符函数名称的完整集合：op_Additionop_Subtraction、op_Multi ply、op_Di vi si on、op_Modulus、op_Bitwi seAnd、op_Bitwiseor、op_Exclusiveor op_Leftshift、op_RightShiop_Equality、 op_lnequality、 op_LessThan op_LessThanOrEqual、 op_GreaterThan 和 op_Greater

28、ThanOrEqual。. 转换运算符具有一个尾随，然后再跟返回类型。namespace Acme(class widget: iProcess (public static explicit operator int(widget x) public static implicit operator long(Widget x) )nM：Acme.Wi dget.op_Expli cit(Acme.Widget)-System.Int32nHM:Acme Wi dget.op_lmpli cit(Acme.widget)-System.Int64n注意，文档文件并不提供有关类型和成员的完整信

29、息（例如，它不包含任何关于 类型的信息）。若要获得有关类型或者成员的完整信息，必须协同使用文档文件 与对实际涉及的类型或者成员的反射调用。A.2.建议的标记文档生成器必须接受和处理任何根据XML规则有效的标记。下列标记提供了用 户文档中常用的功能。（固然，也可能有其他标记。）标记早下用途A.2.1. 将文本设置为类似代码的字体A.2.2. 将一行或者多行源代码或者程序输出设置为某种 字体A.2.3. 表示所含的是示例A.2.4. 标识方法可能引起的异常A.2.5. 包括来自外部文件的XMLA.2.6. 创建列表或者表A.2.7. 用于将结构添加到文本中A.2.8. 描述方法或者构造函数的参数A

30、.2.9. 确认某个单词是参数名A.2.10.描述成员的安全性和访问权限A.2.11.描述一种类型A.2.12.描述方法的返回值A.2.13.指定链接A.2.14.生成“请参见”项A.2.15.描述类型的成员A.2.16.描述属性A.2.1. 此标记提供一种机制以指示用特殊字体（如用于代码块的字体）设置说明中的文 本段落。对于实际代码行，请使用 （第A,2.2. 节）。语法：text示例：/ Class Point models a point in a two-dimensional / plane public class Point( / .A.2.2. 此标记用于将一行或者多行源代码或

31、者程序输出设置为某种特殊字体。对于叙述 中较小的代码段，请使用 (第A.2.1. 节)。语法：source code or program output 示例：/ This method changes the points location by / the given x- and y-offsets./ For example:/ / Point p = new Point(3,5);/ p.Translate(-l,3);/ / results in p1s having the value (2,8)./ / public void Translate(int xor, int yo

32、r) X += xor;Y += yor;)A.2.3. 此标记用于在注释中插入代码示例，以说明如何使用所关联的方法或者其他库 成员。通常，此标记是同标记vcode （第A.2.2. 节）一起使用的。语法:descri pti on示例：有关示例，请参见 (第A.2.2. 节)。A.2.4. 此标记提供一种方法以说明关联的方法可能引起的异常。语法：description其中cref=,membern成员的名称。文档生成器检查给定成员是否存在，并将member转换为文 档文件中的规范元素名称。descri pti on对引起异常的情况的描述。示例：public class DataBaseOpe

33、rations/ / public static void ReadRecord(int flag) if (flag = 1)throw new MasterFi1eFormatCorruptException();else if (flag = 2)throw new MasterFi1eLockedOpenException();/.）A.2.5. 此标记允许包含来自源代码文件外部的XML文档的信息。外部文件必须是符合 标准格式的XML文档，还可以将XPath表达式应用于该文档来指定应包含该 XML文档中的哪些XML文本。然后用从外部文档中选定的XML来替换 标记。语法：其中file=u

34、filenamen外部XML文件的文件名。该文件名是相对于包含include标记的文件进 行解释的（确定其完整路径名）。path=xpathXPath表达式，用于选择外部XML文件中的某些XMLo示例：如果源代码包含了如下声明：/ public class intList . 并且外部文件“docs.xml”含有以下内容：Cou本g与u2 g J与冰。上 与u本G?GL2.cj g22 ug山G二”肆L与u?与2本2n山山gL入Cou本g与u2 g与2本。上与u本G?GL2.这样输出的文档就与源代码中包含以下内容时一样： 2n山山gL入、Cou本g与u2 g J与2本。上与u本G?GL2 .

35、2n山山gL入public class IntList . A,2.6. 此标记用于创建列表或者项目表。它可以包含块以定义表或者定 义列表的标头行。（定义表时，仅需要在标头中为本GL山提供一个项。）列表中的每一项都用一个 与本G山块来描述。创建定义列表时，必须同时指定 本GWJ和qG2cL与b本与ou。但是，对于表、项目符号列表或者编号列表，仅需要指 定 qG2cLb2|souo语法:list type=bullet | number | tablesterm lermdescription descriptionterm iermdescription description term iermdescription description其中term要定义的术语，其定义位于description中。description是项目符号列表或者编号列表中的项，或者是term的定义。示例：public class MyClass/ Here is an example of a bul1 eted list:/ / / ltem 1.