欢迎来到天天文库
浏览记录
ID：20670552
大小：222.68 KB
页数：23页
时间：2018-10-14
《c#文档注释规范》由会员上传分享，免费在线阅读，更多相关内容在工程资料-天天文库。
1、C#文档注释规范C#提供一种机制，使程序员可以使用含冇XML文本的特殊注释语法为他们的代码编写文捫。在源代码文件屮，抖冇某种格式的注释可川丁•指导某个工具根裾这些注释和它们后而的源代码元素生成XMU使川这类语法的注释称力文档注释（documentationcomment）,这些注释后面必须紧跟用户定义类型（如类、娄托或按U）或者成员（如字段、事件、属性或方法）。XML生成工具称作文扔生成器（documentationgenerator）.（此生成器可以但不•“定必须是C#编译器本身。）山文档生成器产生的输出称为文档文件（documentationfile）,文档文
2、件可作力文档杏看器（documentationviewer）的输入：文档卉看器是用于生成类型信息及其关联文档的某种可视化显示的工具。此规范推荐了一组在文档注释中使用的标记，但是这些标记不是必须使用的，如果需要也可以使用其他标记，只要遵循“符合格式标准的XML”规则即可。A.1.介绍具有特殊格式的注释可用于指导某个工具根据这些注释和它们后面的源代码元素生成XML。这类注释是以三个斜杠（///）开始的单行注释，或者是以一个斜杠和两个星号（/**）开始的分隔注释。这些注释后面必须紧跟它们所注释的用户定义类型（如类、委托或接口）或者成员（如字段、事件、属性或方法）。展性节
3、（第错误!未找到引用源。节）被视为声明的一部分，因此，文档注释必须位于应用到类型或成员的属性之前。语法：single-line-doc-comment:///input-charactersoptdelimited-doc-comment:/**delimited-comment-charactersopt*/在single-line-doc-comment中，如果当前single-line-doc-comment旁迈的每个sing!e-line-d（）c-c（）mmenti的///卞符后跟存whitespacet•符，则此whitespace字符不包括在XML输
4、出中。在delimlted-doc-comment中，如果第二行上的第一个非wA/Zapfzce字符是一个asterisk,并且在delimited-doc-comment内的毎行开头都重复同一个由可选whitespace字符和a价字符组成的样式，则该重复出现的样式所含的字符不包括在XML输出中。此样式巾，可以在asterisk字符之前或之后包》括whitespace字符。示例:///ClassPointmodelsapointinatwo-dimensional///pIane-///publicclassPo
5、int{///methoddrawrendersthepoint.voiddraw(){...}}文档注释内的文本必须根据XML规则(http://www.w3.org/TR/REC-xml)设置正确的格式。如果XML不符合标准格式，将生成警告，并且文档文件将包含一条注释，指山遇到错误。尽管开发人员可自由创建它们自己的标记集，但第A.2.建议的标记节定义有建议的标记集。某些建议的标记具有特殊含义：••标记用于描述参数。如果使用这样的标记，文档生成器必须验证指定参数足否存在以及文档注释中是否描述了所宵
6、参数。如果此验证失败，文档屯成器将发出荇告。••cref属性可以附加到彺意标记，以提供对代码元素的参考。文档生成器必须验证此代码元素是否存在。如果验证失败，文朽生成器将发出矜告。査找在cref屈性屮描述的名称吋，文朽生成器必须根据源代码屮出现的using语句來考虑命名空间的可见性。••标记旨在标出可凼文档查看器显示的有关类型或成员的额外信息。••标记表示应该包含的米肖外部xml文件的信息。注意，文档文件并不提供有关类型和成员的完整信息(例如，它不包含任何关于类型的信息)。若要获得有关类型或成员的完整信息，必须协同使用文挡文件与对
7、实际涉及的类型或成员的反射调用。A.2.建议的标记文档生成器必须接受和处理任何根据XML规则有效的标记。K列标记提供丫用户文档中常用的功能。(当然，也可能有其他标记。)标记章节用途A.2.1.将文本设罝为类似代码的字体A.2.2.〈code〉将一行或多行源代码或程序输出设置为某种字体A.2.3.表示所含的是示例A.2.4.标识方法可能引发的异常A.2.5.包括来自外部文件的XML<1ist>A.2.6.创建列表或表
A.2.2.〈code〉将一行或多行源代码或程序输出设置为某种字体A.2.3.表示所含的是示例A.2.4.标识方法可能引发的异常A.2.5.包括来自外部文件的XML<1ist>A.2.6.创建列表或表
8、
此文档下载收益归作者所有
