C#文档注释规范C#提供一种机制，使程序员可以使用含有XML文本的特殊注释语法为他们的代码编写文档。在源代码文件中，具有某种格式的注释可用于指导某个工具根据这些注释和它们后面的源代码元素生成XML。使用这类语法的注释称为文档注释(documentationcomment)。这些注释后面必须紧跟用户定义类型（如类、委托或接口）或者成员（如字段、事件、属性或方法）。XML生成工具称作文档生成器(documentationgenerator)。（此生成器可以但不一定必须是C#编译器本身。）由文档生成器产生的输出称为文档文件(docume...
A.2.2将一行或多行源代码或程序输出设置为某种字体A.2.3表示所含的是示例A.2.4标识方法可能引发的异常A.2.5包括来自外部文件的XMLA.2.6创建列表或表A.2.7用于将结构添加到文本中A.2.8描述方法或构造函数的参数A.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 示例：///ClassPoint modelsapointinatwo-dimensional///plane. publicclassPoint{//...}A.2.2. 此标记用于将一行或多行源代码或程序输出设置为某种特殊字体。对于叙述中较小的代码段，请使用（第A.2.1节）。语法：sourcecodeorprogramoutput示例：///Thismethodchangesthepoint'slocationby/// thegivenx-andy-offsets.///Forexample:////// Pointp=newPoint(3,5);/// p.Translate(-1,3);//////resultsinp 'shavingthevalue(2,8)./// /// publicvoidTranslate(intxor,intyor){X=xor;Y=yor;} A.2.3. 此标记用于在注释中插入代码示例，以说明如何使用所关联的方法或其他库成员。通常，此标记是同标记（第A.2.2节）一起使用的。语法：description 示例：有关示例，请参见（第A.2.2节）。A.2.4. 此标记提供一种方法以说明关联的方法可能引发的异常。语法：description 其中cref="member"成员的名称。文档生成器检查给定成员是否存在，并将member转换为文档文件中的规范元素名称。description对引发异常的情况的描述。示例：publicclassDataBaseOperations{///
///publicstaticvoidReadRecord(intflag){if(flag==1)thrownewMasterFileFormatCorruptException();elseif(flag==2)thrownewMasterFileLockedOpenException();//…}}A.2.5. 此标记允许包含来自源代码文件外部的XML文档的信息。外部文件必须是符合标准格式的XML文档，还可以将XPath表达式应用于该文档来指定应包含该XML文档中的哪些XML文本。然后用从外部文档中选定的XML来替换标记。语法：Containsalistofintegers. Containsalistofintegers. /// Containsalistofintegers./// publicclassIntList{…}A.2.6. 此标记用于创建列表或项目表。它可以包含块以定义表或定义列表的标头行。（定义表时，仅需要在标头中为term提供一个项。）列表中的每一项都用一个- 块来描述。创建定义列表时，必须同时指定term和description。但是，对于表、项目符号列表或编号列表，仅需要指定description。语法：
term description term description term description
其中term要定义的术语，其定义位于description中。description是项目符号列表或编号列表中的项，或者是term的定义。示例：publicclassMyClass{///Hereisanexampleofabulletedlist://////- ///
Item1. /// ///- ///
Item2. /// ////// publicstaticvoidMain(){//...}}A.2.7. 此标记用于其他标记内，如（第A.2.11节）或（第A.2.12节），用于将结构添加到文本中。语法：content 其中content段落文本。示例：///ThisistheentrypointofthePointclasstestingprogram.///Thisprogramtestseachmethodandoperator,and///isintendedtoberunafteranynon-trvialmaintenancehas///beenperformedonthePointclass. publicstaticvoidMain(){//...}A.2.8. 该标记用于描述方法、构造函数或索引器的参数。语法：description其中name参数名。description参数的描述。示例：///Thismethodchangesthepoint'slocationto/// thegivencoordinates. ///thenewx-coordinate.///thenewy-coordinate.publicvoidMove(intxor,intyor){X=xor;Y=yor;}A.2.9. 该标记表示某单词是一个参数。这样，生成文档文件后经适当处理，可以用某种独特的方法来格式化该参数。语法：ThisconstructorinitializesthenewPointto/// ( ///thenewPoint'sx-coordinate.///thenewPoint'sy-coordinate.publicPoint(intxor,intyor){X=xor;Y=yor;}A.2.10.该标记用于将成员的安全性和可访问性记入文档。语法：description 其中cref="member"成员的名称。文档生成器检查给定的代码元素是否存在，并将member转换为文档文件中的规范化元素名称。description对成员的访问属性的说明。示例：///Everyonecan///accessthismethod.publicstaticvoidTest(){//...}A.2.11.该标记用于指定类型的概述信息。（使用（第A.2.15节）描述类型的成员。）语法：description 其中description摘要文本。示例：///ClassPoint modelsapointina///two-dimensionalplane. publicclassPoint{//...}A.2.12.该标记用于描述方法的返回值。语法：description 其中description返回值的说明。示例：///Reportapoint'slocationasastring. ///Astringrepresentingapoint'slocation,intheform(x,y),/// withoutanyleading,trailing,orembeddedwhitespace. publicoverridestringToString(){return"("X","Y")";}A.2.13.该标记用于在文本内指定链接。使用（第A.2.14节）指示将在“请参见”部分中出现的文本。语法：Thismethodchangesthepoint'slocationto/// thegivencoordinates. ///Thismethodchangesthepoint'slocationby/// thegivenx-andy-offsets./// ///该标记用于生成将列入“请参见”部分的项。使用（第A.2.13节）指定来自文本内的链接。语法：ThismethoddetermineswhethertwoPointshavethesame/// location. ///可以用此标记描述类型的成员。使用（第A.2.11节）描述类型本身。语法：description 其中description关于成员的摘要描述。示例：///ThisconstructorinitializesthenewPointto(0,0). publicPoint():this(0,0){}A.2.16.该标记用于描述属性。语法：propertydescription 其中propertydescription属性的说明。示例：///PropertyX representsthepoint'sx-coordinate. publicintX{get{returnx;}set{x=value;}}A.3. 处理文档文件文档生成器为源代码中每个附加了“文档注释标记”的代码元素生成一个ID字符串。该ID字符串唯一地标识源元素。文档查看器利用此ID字符串来标识该文档所描述的对应的元数据/反射项。文档文件不是源代码的层次化表现形式；而是为每个元素生成的ID字符串的一维列表。A.3.1. ID字符串格式文档生成器在生成ID字符串时遵循下列规则：● 不在字符串中放置空白。● 字符串的第一部分通过单个字符后跟一个冒号来标识被标识成员的种类。定义以下几种成员：字符说明E事件F字段M方法（包括构造函数、析构函数和运算符）N命名空间P属性（包括索引器）T类型（如类、委托、枚举、接口和结构）!错误字符串；字符串的其他部分提供有关错误的信息。例如，文档生成器对无法解析的链接生成错误信息。● 字符串的第二部分是元素的完全限定名，从命名空间的根开始。元素的名称、包含着它的类型和命名空间都以句点分隔。如果项名本身含有句点，则将用#(U0023)字符替换。（这里假定所有元素名中都没有“#(U0023)”字符。）● 对于带有参数的方法和属性，接着是用括号括起来的参数列表。对于那些不带参数的方法和属性，则省略括号。多个参数以逗号分隔。每个参数的编码都与CLI签名相同，如下所示：参数由其完全限定名来表示。例如，int变成System.Int32、string变成System.String、object变成System.Object等。具有out或ref修饰符的参数在其类型名后跟有@符。对于由值传递或通过params传递的参数没有特殊表示法。数组参数表示为[lowerbound:size,…,lowerbound:size]，其中逗号数量等于秩减去一，而下限和每个维的大小（如果已知）用十进制数表示。如果未指定下限或大小，它将被省略。如果省略了某个特定维的下限及大小，则“:”也将被省略。交错数组由每个级别一个“[]”来表示。指针类型为非void的参数用类型名后面跟一个*的形式来表示。void指针用类型名System.Void表示。A.3.2. ID字符串示例下列各个示例分别演示一段C#代码以及为每个可以含有文档注释的源元素生成的ID字符串：● 类型用它们的完全限定名来表示。enumColor{Red,Blue,Green}namespaceAcme{interfaceIProcess{...}structValueType{...}classWidget:IProcess{publicclassNestedClass{...}publicinterfaceIMenuItem{...}publicdelegatevoidDel(inti);publicenumDirection{North,South,East,West}}}"T:Color""T:Acme.IProcess""T:Acme.ValueType""T:Acme.Widget""T:Acme.Widget.NestedClass""T:Acme.Widget.IMenuItem""T:Acme.Widget.Del""T:Acme.Widget.Direction"● 字段用它们的完全限定名来表示。namespaceAcme{structValueType{privateinttotal;}classWidget:IProcess{publicclassNestedClass{privateintvalue;}privatestringmessage;privatestaticColordefaultColor;privateconstdoublePI=3.14159;protectedreadonlydoublemonthlyAverage;privatelong[]array1;privateWidget[,]array2;privateunsafeint*pCount;privateunsafefloat**ppValues;}}"F:Acme.ValueType.total""F:Acme.Widget.NestedClass.value""F:Acme.Widget.message""F:Acme.Widget.defaultColor""F:Acme.Widget.PI""F:Acme.Widget.monthlyAverage""F:Acme.Widget.array1""F:Acme.Widget.array2""F:Acme.Widget.pCount""F:Acme.Widget.ppValues"● 构造函数。namespaceAcme{classWidget:IProcess{staticWidget(){...}publicWidget(){...}publicWidget(strings){...}}}"M:Acme.Widget.#cctor""M:Acme.Widget.#ctor""M:Acme.Widget.#ctor(System.String)"● 析构函数。namespaceAcme{classWidget:IProcess{~Widget(){...}}}"M:Acme.Widget.Finalize"● 方法。namespaceAcme{structValueType{publicvoidM(inti){...}}classWidget:IProcess{publicclassNestedClass{publicvoidM(inti){...}}publicstaticvoidM0(){...}publicvoidM1(charc,outfloatf,refValueTypev){...}publicvoidM2(short[]x1,int[,]x2,long[][]x3){...}publicvoidM3(long[][]x3,Widget[][,,]x4){...}publicunsafevoidM4(char*pc,Color**pf){...}publicunsafevoidM5(void*pv,double*[][,]pd){...}publicvoidM6(inti,paramsobject[]args){...}}}"M:Acme.ValueType.M(System.Int32)""M:Acme.Widget.NestedClass.M(System.Int32)""M:Acme.Widget.M0""M:Acme.Widget.M1(System.Char,System.Single@,Acme.ValueType@)""M:Acme.Widget.M2(System.Int16[],System.Int32[0:,0:],System.Int64[][])""M:Acme.Widget.M3(System.Int64[][],Acme.Widget[0:,0:,0:][])""M:Acme.Widget.M4(System.Char*,Color**)""M:Acme.Widget.M5(System.Void*,System.Double*[0:,0:][])""M:Acme.Widget.M6(System.Int32,System.Object[])"● 属性和索引器。namespaceAcme{classWidget:IProcess{publicintWidth{get{...}set{...}}publicintthis[inti]{get{...}set{...}}publicintthis[strings,inti]{get{...}set{...}}}}"P:Acme.Widget.Width""P:Acme.Widget.Item(System.Int32)""P:Acme.Widget.Item(System.String,System.Int32)"● 事件。namespaceAcme{classWidget:IProcess{publiceventDelAnEvent;}}"E:Acme.Widget.AnEvent"● 一元运算符。namespaceAcme{classWidget:IProcess{publicstaticWidgetoperator(Widgetx){...}}}"M:Acme.Widget.op_UnaryPlus(Acme.Widget)"下面列出可使用的一元运算符函数名称的完整集合：op_UnaryPlus、op_UnaryNegation、op_LogicalNot、op_OnesComplement、op_Increment、op_Decrement、op_True和op_False。● 二元运算符。namespaceAcme{classWidget:IProcess{publicstaticWidgetoperator(Widgetx1,Widgetx2){...}}}"M:Acme.Widget.op_Addition(Acme.Widget,Acme.Widget)"下面列出可使用的二元运算符函数名称的完整集合：op_Addition、op_Subtraction、op_Multiply、op_Division、op_Modulus、op_BitwiseAnd、op_BitwiseOr、op_ExclusiveOr、op_LeftShift、op_RightShift、op_Equality、op_Inequality、op_LessThan、op_LessThanOrEqual、op_GreaterThan和op_GreaterThanOrEqual。● 转换运算符具有一个尾随“~”，然后再跟返回类型。namespaceAcme{classWidget:IProcess{publicstaticexplicitoperatorint(Widgetx){...}publicstaticimplicitoperatorlong(Widgetx){...}}}"M:Acme.Widget.op_Explicit(Acme.Widget)~System.Int32""M:Acme.Widget.op_Implicit(Acme.Widget)~System.Int64" 
浙公网安备 33021202002483