择外部 XML 文件中的某些 XML。
示例: 如果源代码包含了如下声明: /// ltinclude filequotdocs.xmlquot pathextradoc/classnamequotIntListquot/ /gt public class IntList … 并且外部文件“docs.xml”含有以下内容: ltxml versionquot1.0quotgt ltextradocgt ltclass namequotIntListquotgt ltsummarygt Contains a list of integers. lt/summarygt lt/classgt ltclass namequotStringListquotgt ltsummarygt Contains a list of integers. lt/summarygt lt/classgt lt/extradocgt 这样输出的文档就与源代码中包含以下内容时一样: /// ltsummarygt /// Contains a list of integers. /// lt/summarygt public class IntList … A.2.6.ltlistgt 此标记用于创建列表或项目表。
它可以包含 ltlistheadergt 块以定义表或定义列表的标头行。
(定义表时,仅需要在标头中为 term 提供一个项。
) 列表中的每一项都用一个 ltitemgt 块来描述。
创建定义列表时,必须同时指定 term 和description。
但是,对于表、项目符号列表或编号列表,仅需要指定 description。
语法: ltlist typequotbulletquot quotnumberquot quottablequotgt ltlistheadergt lttermgttermlt/termgt ltdescriptiongtdescriptionlt/descriptiongt lt/listheadergt ltitemgt lttermgttermlt/termgt ltdescriptiongtdescriptionlt/descriptiongt lt/itemgt … ltitemgt lttermgttermlt/termgt ltdescriptiongtdescriptionlt/descriptiongt lt/itemgt lt/listgt其中 term 要定义的术语,其定义位于 description 中。
description 是项目符号列表或编号列表中的项,或者是 term 的定义。
示例: public class MyClass /// ltsummarygtHere is an example of a bulleted list: /// ltlist typequotbulletquotgt /// ltitemgt /// ltdescriptiongtItem 1.lt/descriptiongt /// lt/itemgt /// ltitemgt /// ltdescriptiongtItem 2.lt/descriptiongt /// lt/itemgt /// lt/listgt /// lt/summarygt public static void Main // ... A.2.7.ltparagt 此标记用于其他标记内, (第 A.2.11 节 如ltsummarygt (第 A.2.12 节 )或ltreturnsgt ),用于将结构添加到文本中。
语法: ltparagtcontentlt/paragt 其中 content 段落文本。
示例: /// ltsummarygtThis is the entry point of the Point class testing program. /// ltparagtThis program tests each method and operator and /// is intended to be run after any non-trvial maintenance has /// been performed on the Point class.lt/paragtlt/summarygt public static void Main // ... A.2.8.ltparamgt 该标记用于描述方法、构造函数或索引器的参数。
语法: ltparam namequotnamequotgtdescriptionlt/paramgt 其中 name 参数名。
description 参数的描述。
示例: /// ltsummarygtThis method changes the points location to /// the given coordinates.lt/summarygt /// ltparam namequotxorquotgtthe new x-coordinate.lt/paramgt /// ltparam namequotyorquotgtthe new y-coordinate.lt/paramgt public void Moveintxor intyor X xor Y yor A.2.9.ltparamrefgt 该标记表示某单词是一个参数。
这样,生成文档文件后经适当处理,可以用某种独特的方法来格式化该参数。
语法: ltparamref namequotnamequot/gt 其中 name 参数名。
示例: /// ltsummarygtThis constructor initializes the new Point to /// ltparamref namequotxorquot/gtltparamref namequotyorquot/gt.lt/summarygt /// ltparam namequotxorquotgtthe new Points x-coordinate.lt/paramgt /// ltparam namequotyorquotgtthe new Points y-coordinate.lt/paramgt public Pointintxor intyor X xor Y yor A.2.10.ltpermissiongt该标记用于将成员的安全性和可访问性记入文档。
语法: ltpermission crefquotmemberquotgtdescriptionlt/permissiongt其中 crefquotmemberquot 成员的名称。
文档生成器检查给定的代码元素是否存在,并将 member 转换为文 档文件中的规范化元素名称。
description 对成员的访问属性的说明。
示例: /// ltpermission crefquotSystem.Security.PermissionSetquotgtEveryone can ///
access this method.lt/permissiongt public static void Test // ... A.2.11.ltsummarygt该标记用于指定类型的概述信息。
(第 A.2.15 节) (使用ltsummarygt 描述类型的成员。
)语法: ltsummarygtdescriptionlt/summarygt其中 description 摘要文本。
示例: /// ltsummarygtClass ltcgtPointlt/cgt models a point in a /// two-dimensional plane.lt/summarygt public class Point // ... A.2.12.ltreturnsgt该标记用于描述方法的返回值。
语法: ltreturnsgtdescriptionlt/returnsgt其中 description 返回值的说明。
示例: /// ltsummarygtReport a points location as a string.lt/summarygt /// ltreturnsgtA string representing a points location in the form xy /// without any leading trailing or embedded whitespace.lt/returnsgt public override string ToString return quotquot X quotquot Y quotquot A.2.13.ltseegt 该标记用于在文本内指定链接。
使用ltseealsogt(第 A.2.14 节)指示将在“请参见”部分中出现的文本。
语法: ltsee crefquotmemberquot/gt 其中 crefquotmemberquot 成员的名称。
文档生成器检查给定的代码元素是否存在,并将 member 更改为所 生成的文档文件中的元素名称。
示例: /// ltsummarygtThis method changes the points location to /// the given coordinates.lt/summarygt /// ltsee crefquotTranslatequot/gt public void Moveintxor intyor X xor Y yor /// ltsummarygtThis method changes the points location by /// the given x- and y-offsets. /// lt/summarygt /// ltsee crefquotMovequot/gt public void Translateintxor intyor X xor Y yor A.2.14.ltseealsogt 该标记用于生成将列入“请参见”部分的项。
使用 ltseegt(第 A.2.13 节)指定来自文本内的链接。
语法: ltseealsocrefquotmemberquot/gt其中 crefquotmemberquot 成员的名称。
文档生成器检查给定的代码元素是否存在,并将 member 更改为所 生成的文档文件中的元素名称。
示例: /// ltsummarygtThis method determines whether two Points have the same /// location.lt/summarygt /// ltseealsocrefquotoperatorquot/gt /// ltseealsocrefquotoperatorquot/gt public override bool Equalsobject o // ... A.2.15.ltsummarygt可以用此标记描述类型的成员。
使用ltsummarygt(第 A.2.11 节)描述类型本身。
语法: ltsummarygtdescriptionlt/summarygt其中 description 关于成员的摘要描述。
示例: /// ltsummarygtThis constructor initializes the new Point to 00.lt/summarygt public Point : this00 A.2.16.ltvaluegt该标记用于描述属性。
语法: ltvaluegtpropertydescriptionlt/valuegt其中 property description 属性的说明。
示例: /// ltvaluegtProperty ltcgtXlt/cgt represents the points x-coordinate.lt/valuegt public int X get return x 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字符串: 类型用它们的完全限定名来表示。
enum Color Red Blue Green namespace Acme interface IProcess ... structValueType ... class Widget: IProcesspublic class NestedClass ... public interface IMenuItem ... public delegate void Delint i publicenum Direction N.
上一篇:
常用文件扩展名(超全)
下一篇:
电咖汽车入选2018独角兽企业榜百强 发布“天际”品牌将推高估值