【ACCESS精品源码栏目提醒】:网学会员ACCESS精品源码为您提供C#文档注释规范 - 其它资料参考,解决您在C#文档注释规范 - 其它资料学习中工作中的难题,参考学习。
C 文档注释规范 C 提供一种机制,使程序员可以使用含有 XML 文本的特殊注释语法为他们的代码编写文档。
在源代码文件中,具有某种格式的注释可用于指导某个工具根据这些注释和它们后面的源代码元素生成 XML。
使用这类语法的注释称为文档注释 documentation comment。
这些注释后面必须紧跟用户定义类型(如类、委托或接口)或者成员(如字段、事件、属性或方法)。
XML 生成工具称作文档生成器documentation generator。
(此生成器可以但不一定必须是 C 编译器本身。
)由文档生成器产生的输出称为文档文件 documentationfile。
文档文件可作为文档查看器documentation viewer 的输入;文档查看器是用于生成类型信息及其关联文档的某种可视化显示的工具。
此规范推荐了一组在文档注释中使用的标记,但是这些标记不是必须使用的,如果需要也可以使用其他标记,只要遵循“符合格式标准的 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 字符。
示例: /// ltsummarygtClass ltcgtPointlt/cgt models a point in a two-dimensional /// plane.lt/summarygt /// public class Point /// ltsummarygtmethod ltcgtdrawlt/cgt renders the point.lt/summarygt void draw … 文档注释内的文本必须根据 XML 规则 http://www.w3.org/TR/REC-xml 设置正确的格式。
如果 XML 不符合标准格式,将生成警告,并且文档文件将包含一条注释,指出遇到错误。
尽管开发人员可自由创建它们自己的标记集,但第 A.2 节定义有建议的标记集。
某些建议的标记具有特殊含义: ltparamgt标记用于描述参数。
如果使用这样的标记,文档生成器必须验证指定参数 是否存在以及文档注释中是否描述了所有参数。
如果此验证失败,文档生成器将发出警告。
cref 属性可以附加到任意标记,以提供对代码元素的参考。
文档生成器必须验证此代 码元素是否存在。
如果验证失败,文档生成器将发出警告。
查找在 cref 属性中描述的名称 时,文档生成器必须根据源代码中出现的 using 语句来考虑命名空间的可见性。
ltsummarygt标记旨在标出可由文档查看器显示的有关类型或成员的额外信息。
ltincludegt标记表示应该包含的来自外部 XML 文件的信息。
注意,文档文件并不提供有关类型和成员的完整信息(例如,它不包含任何关于类型的信息)。
若要获得有关类型或成员的完整信息,必须协同使用文档文件与对实际涉及的类型或成员的反射调用。
A.2.建议的标记 文档生成器必须接受和处理任何根据 XML 规则有效的标记。
下列标记提供了用户文档中常用的功能。
(当然,也可能有其他标记。
) 标记 章节 用途 ltcgt A.2.1 将文本设置为类似代码的字体 ltcodegt A.2.2 将一行或多行源代码或程序输出设置为某种字体 ltexample A.2.3 表示所含的是示例