c#文档注释规范Word格式.docx
《c#文档注释规范Word格式.docx》由会员分享，可在线阅读，更多相关《c#文档注释规范Word格式.docx（16页珍藏版）》请在冰豆网上搜索。
{
///<
method<
draw<
rendersthepoint.<
voiddraw（）{…}
}
文档注释内的文本必须根据XML规则（http:
//www.w3.org/TR/REC-xml）设置正确的格式。
如果XML不符合标准格式，将生成警告，并且文档文件将包含一条注释，指出遇到错误。
尽管开发人员可自由创建它们自己的标记集，但第A.2节定义有建议的标记集。
某些建议的标记具有特殊含义：
●∙
<
param>
标记用于描述参数。
如果使用这样的标记，文档生成器必须验证指定参数是否存在以及文档注释中是否描述了所有参数。
如果此验证失败，文档生成器将发出警告。
cref属性可以附加到任意标记，以提供对代码元素的参考。
文档生成器必须验证此代码元素是否存在。
如果验证失败，文档生成器将发出警告。
查找在cref属性中描述的名称时，文档生成器必须根据源代码中出现的using语句来考虑命名空间的可见性。
标记旨在标出可由文档查看器显示的有关类型或成员的额外信息。
include>
标记表示应该包含的来自外部XML文件的信息。
注意，文档文件并不提供有关类型和成员的完整信息（例如，它不包含任何关于类型的信息）。
若要获得有关类型或成员的完整信息，必须协同使用文档文件与对实际涉及的类型或成员的反射调用。
A.2.
建议的标记
文档生成器必须接受和处理任何根据XML规则有效的标记。
下列标记提供了用户文档中常用的功能。
（当然，也可能有其他标记。
）
标记
章节
用途
<
A.2.1
将文本设置为类似代码的字体
code>
A.2.2
将一行或多行源代码或程序输出设置为某种字体
example>
A.2.3
表示所含的是示例
exception>
A.2.4
标识方法可能引发的异常
A.2.5
包括来自外部文件的XML
list>
A.2.6
创建列表或表
para>
A.2.7
用于将结构添加到文本中
A.2.8
描述方法或构造函数的参数
paramref>
A.2.9
确认某个单词是参数名
permission>
A.2.10
描述成员的安全性和访问权限
A.2.11
描述一种类型
returns>
A.2.12
描述方法的返回值
see>
A.2.13
指定链接
seealso>
A.2.14
生成“请参见”项
A.2.15
描述类型的成员
value>
A.2.16
描述属性
A.2.1.
此标记提供一种机制以指示用特殊字体（如用于代码块的字体）设置说明中的文本段落。
对于实际代码行，请使用<
（第A.2.2节）。
text<
//...
A.2.2.
此标记用于将一行或多行源代码或程序输出设置为某种特殊字体。
对于叙述中较小的代码段，请使用<
（第A.2.1节）。
sourcecodeorprogramoutput<
/code>
Thismethodchangesthepoint'
slocationby
///thegivenx-andy-offsets.
Forexample:
///Pointp=newPoint（3,5）;
///p.Translate（-1,3）;
///resultsin<
p<
'
shavingthevalue（2,8）.
/example>
publicvoidTranslate（intxor,intyor）{
X+=xor;
Y+=yor;
}
A.2.3.
此标记用于在注释中插入代码示例，以说明如何使用所关联的方法或其他库成员。
通常，此标记是同标记<
（第A.2.2节）一起使用的。
description<
有关示例，请参见<
A.2.4.
此标记提供一种方法以说明关联的方法可能引发的异常。
exceptioncref="
member"
>
/exception>
其中
cref="
成员的名称。
文档生成器检查给定成员是否存在，并将member转换为文档文件中的规范元素名称。
description
对引发异常的情况的描述。
publicclassDataBaseOperations
MasterFileFormatCorruptException"
MasterFileLockedOpenException"
publicstaticvoidReadRecord（intflag）{
if（flag==1）
thrownewMasterFileFormatCorruptException（）;
elseif（flag==2）
thrownewMasterFileLockedOpenException（）;
//…
}
A.2.5.
此标记允许包含来自源代码文件外部的XML文档的信息。
外部文件必须是符合标准格式的XML文档，还可以将XPath表达式应用于该文档来指定应包含该XML文档中的哪些XML文本。
然后用从外部文档中选定的XML来替换<
标记。
includefile="
filename"
path="
xpath"
/>
file="
外部XML文件的文件名。
该文件名是相对于包含include标记的文件进行解释的（确定其完整路径名）。
path="
XPath表达式，用于选择外部XML文件中的某些XML。
如果源代码包含了如下声明：
docs.xml"
path='
extradoc/class[@name="
IntList"
]/*'
publicclassIntList{…}
并且外部文件“docs.xml”含有以下内容：
?
xmlversion="
1.0"
extradoc>
classname="
Containsalistofintegers.
/class>
StringList"
/extradoc>
这样输出的文档就与源代码中包含以下内容时一样：
///Containsalistofintegers.
A.2.6.
此标记用于创建列表或项目表。
它可以包含<
listheader>
块以定义表或定义列表的标头行。
（定义表时，仅需要在标头中为term提供一个项。
列表中的每一项都用一个<
item>
块来描述。
创建定义列表时，必须同时指定term和description。
但是，对于表、项目符号列表或编号列表，仅需要指定description。
listtype="
bullet"
|"
number"
table"
term>
term<
/term>
description>
/description>
/listheader>
/item>
…
/list>
term
要定义的术语，其定义位于description中。
description
是项目符号列表或编号列表中的项，或者是term的定义。
publicclassMyClass
Hereisanexampleofabulletedlist:
Item1.<
Item2.<
publicstaticvoidMain（）{
//...
}
A.2.7.
此标记用于其他标记内，如<
（第A.2.11节）或<
（第A.2.12节），用于将结构添加到文本中。
content<
/para>
content
段落文本。
ThisistheentrypointofthePointclasstestingprogram.
Thisprogramtestseachmethodandoperator,and
///isintendedtoberunafteranynon-trvialmaintenancehas
///beenperformedonthePointclass.<
publicstaticvoidMain（）{
A.2.8.
该标记用于描述方法、构造函数或索引器的参数。
paramname="
name"
/param>
name
参数名。
参数的描述。
slocationto
///thegivencoordinates.<
xor"
thenewx-coordinate.<
yor"
thenewy-coordinate.<
publicvoidMove（intxor,intyor）{
X=xor;
Y=yor;
A.2.9.
该标记表示某单词是一个参数。
这样，生成文档文件后经适当处理，可以用某种独特的方法来格式化该参数。
paramrefname="
/>
name
ThisconstructorinitializesthenewPointto
///（<
<
）.<
thenewPoint'
sx-coordinate.<
sy-coordinate.<
publicPoint（intxor,intyor）{
A.2.10.<
该标记用于将成员的安全性和可访问性记入文档。
permissioncref="
/permission>
文档生成器检查给定的代码元素是否存在，并将member转换为文档文件中的规范化元素名称。
对成员的访问属性的说明。
System.Security.PermissionSet"
Everyonecan
///accessthismethod.<
publicstaticvoidTest（）{
A.2.11.<
该标记用于指定类型的概述信息。
（使用<
（第A.2.15节）描述类型的成员。
摘要文本。
modelsapointina
///two-dimensionalplane.<
A.2.12.<
该标记用于描述方法的返回值。
/returns>
返回值的说明。
Reportapoint'
slocationasastring.<
Astringrepresentingapoint'
slocation,intheform（x,y）,
///withoutanyleading,trailing,orembeddedwhitespace.<
publicoverridestringToString（）{
return"
（"
+X+"
"
+Y+"
）"
;
A.2.13.<
该标记用于在文本内指定链接。
使用<
（第A.2.14节）指示将在“请参见”部分中出现的
文本。
seecref="
文档生成器检查给定的代码元素是否存在，并将member更改为所生成的文档文件中的元素名称。
Translate"
Move"
A.2.14.<
该标记用于生成将列入“请参见”部分的项。
（第A.2.13节）指定来自文本内的链接。
seealsocref="
ThismethoddetermineswhethertwoPointshavethesame
///location.<
operator=="
operator!
="
publicoverrideboolEquals（objecto）{
A.2.15.<
可以用此标记描述类型的成员。
（第A.2.11节）描述类型本身。
关于成员的摘要描述。
ThisconstructorinitializesthenewPointto（0,0）.<
publicPoint（）:
this（0,0）{
A.2.16.<
该标记用于描述属性。
propertydescription<
/value>
propertydescription
属性的说明。
Property<
X<
representsthepoint'
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）”字符。
对于带有参数的方法和属性
升级会员 