c#文档注释规范.docx
《c#文档注释规范.docx》由会员分享，可在线阅读，更多相关《c#文档注释规范.docx（16页珍藏版）》请在冰豆网上搜索。
c#文档注释规范
C#提供一种机制，使程序员可以使用含有XML文本的特殊注释语法为他们的代码编写文档。
在源代码文件中，具有某种格式的注释可用于指导某个工具根据这些注释和它们后面的源代码元素生成XML。
使用这类语法的注释称为文档注释（documentationcomment）。
这些注释后面必须紧跟用户定义类型（如类、委托或接口）或者成员（如字段、事件、属性或方法）。
XML生成工具称作文档生成器（documentationgenerator）。
（此生成器可以但不一定必须是C#编译器本身。
）由文档生成器产生的输出称为文档文件（documentationfile）。
文档文件可作为文档查看器（documentationviewer）的输入；文档查看器是用于生成类型信息及其关联文档的某种可视化显示的工具。
此规范推荐了一组在文档注释中使用的标记，但是这些标记不是必须使用的，如果需要也可以使用其他标记，只要遵循“符合格式标准的XML”规则即可。
A.1. 介绍
具有特殊格式的注释可用于指导某个工具根据这些注释和它们后面的源代码元素生成XML。
这类注释是以三个斜杠（///）开始的单行注释，或者是以一个斜杠和两个星号（/**）开始的分隔注释。
这些注释后面必须紧跟它们所注释的用户定义类型（如类、委托或接口）或者成员（如字段、事件、属性或方法）。
属性节（第17.2节）被视为声明的一部分，因此，文档注释必须位于应用到类型或成员的属性之前。
语法：
single-line-doc-comment:
///input-charactersopt
delimited-doc-comment:
/**delimited-comment-charactersopt*/
在single-line-doc-comment中，如果当前single-line-doc-comment旁边的每个single-line-doc-comment上的///字符后跟有whitespace字符，则此whitespace字符不包括在XML输出中。
在delimited-doc-comment中，如果第二行上的第一个非whitespace字符是一个asterisk，并且在delimited-doc-comment内的每行开头都重复同一个由可选whitespace字符和asterisk字符组成的样式，则该重复出现的样式所含的字符不包括在XML输出中。
此样式中，可以在asterisk字符之前或之后包括whitespace字符。
示例：
///ClassPointmodelsapointinatwo-dimensional
///plane.
///
publicclassPoint
{
///methoddrawrendersthepoint.
voiddraw（）{…}
}
文档注释内的文本必须根据XML规则（http:
//www.w3.org/TR/REC-xml）设置正确的格式。
如果XML不符合标准格式，将生成警告，并且文档文件将包含一条注释，指出遇到错误。
尽管开发人员可自由创建它们自己的标记集，但第A.2节定义有建议的标记集。
某些建议的标记具有特殊含义：
●∙ 标记用于描述参数。
如果使用这样的标记，文档生成器必须验证指定参数是否存在以及文档注释中是否描述了所有参数。
如果此验证失败，文档生成器将发出警告。
●∙ cref属性可以附加到任意标记，以提供对代码元素的参考。
文档生成器必须验证此代码元素是否存在。
如果验证失败，文档生成器将发出警告。
查找在cref属性中描述的名称时，文档生成器必须根据源代码中出现的using语句来考虑命名空间的可见性。
●∙ 标记旨在标出可由文档查看器显示的有关类型或成员的额外信息。
●∙ 标记表示应该包含的来自外部XML文件的信息。
注意，文档文件并不提供有关类型和成员的完整信息（例如，它不包含任何关于类型的信息）。
若要获得有关类型或成员的完整信息，必须协同使用文档文件与对实际涉及的类型或成员的反射调用。
A.2. 建议的标记
文档生成器必须接受和处理任何根据XML规则有效的标记。
下列标记提供了用户文档中常用的功能。
（当然，也可能有其他标记。
）
标记
章节
用途
A.2.1
将文本设置为类似代码的字体
A.2.2
将一行或多行源代码或程序输出设置为某种字体
A.2.3
表示所含的是示例
A.2.4
标识方法可能引发的异常
A.2.5
包括来自外部文件的XML
A.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
示例：
///ClassPointmodelsapointinatwo-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来替换标记。
语法：
其中
file="filename"
外部XML文件的文件名。
该文件名是相对于包含include标记的文件进行解释的（确定其完整路径名）。
path="xpath"
XPath表达式，用于选择外部XML文件中的某些XML。
示例：
如果源代码包含了如下声明：
///
publicclassIntList{…}
并且外部文件“docs.xml”含有以下内容：
xmlversion="1.0"?
>
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.
该标记表示某单词是一个参数。
这样，生成文档文件后经适当处理，可以用某种独特的方法来格式化该参数。
语法：
其中
name
参数名。
示例：
///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
摘要文本。
示例：
///ClassPointmodelsapointina
///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节）指示将在“请参见”部分中出现的
文本。
语法：
其中
cref="member"
成员的名称。
文档生成器检查给定的代码元素是否存在，并将member更改为所生成的文档文件中的元素名称。
示例：
///Thismethodchangesthepoint'slocationto
///thegivencoordinates.
///
publicvoidMove（intxor,intyor）{
X=xor;
Y=yor;
}
///Thismethodchangesthepoint'slocationby
///thegivenx-andy-offsets.
///
///
publicvoidTranslate（intxor,intyor）{
X+=xor;
Y+=yor;
}
A.2.14.
该标记用于生成将列入“请参见”部分的项。
使用（第A.2.13节）指定来自文本内的链接。
语法：
其中
cref="member"
成员的名称。
文档生成器检查给定的代码元素是否存在，并将member更改为所生成的文档文件中的元素名称。
示例：
///ThismethoddetermineswhethertwoPointshavethesame
///location.
///
///="/>
publicoverrideboolEquals（objecto）{
//...
}
A.2.15.
可以用此标记描述类型的成员。
使用（第A.2.11节）描述类型本身。
语法：
description
其中
description
关于成员的摘要描述。
示例：
///ThisconstructorinitializesthenewPointto（0,0）.
publicPoint（）:
this（0,0）{
}
A.2.16.
该标记用于描述属性。
语法：
propertydescription
其中
propertydescription
属性的说明。
示例：
///PropertyXrepresentsthepoint'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
类型（如类、委托、枚举、接口和结构）
!
错误字符串；字符串的其他部分提供有关错误的信息。
例如，文档生成器对无法解析的链接生成错误信息。
●∙ 字符串的第二部分是元素的完全限定名，从命名空间的根开始。
元素的名称、包含着它的类型和命名空间都以句点分隔。
如果项名本身含有句点，则将用#（U+0023）字符替换。
（这里假定所有元素名中都没有“#（U+0023）”字符。
）
●∙ 对于带有参数的方法和属性
升级会员 