《C#编程入门与应用》—2.7.3　文档注释

2.7.3　文档注释 

       C# 提供一种机制，使开发人员可以使用含有XML 文本的特殊注释语法为他们的代 码编写文档。在源代码文件中，具有某种格 式的注释可用于指导某个工具根据这些注释 和它们后面的源代码元素生成 XML。使用这 类语法的注释称为文档注释(Documentation Comment)，有的资料会称为 XML 注释。

       文档注释用于对类或者方法进行描述。 在类或者方法前面连续输入 3 个“/”，就会 自动生成相应的文档注释，用户需要手动填 写类或方法的描述信息，来完成文档注释的 内容。 

       所有的文档注释都在3个斜线“/”之后， “///”与“//”不同，“//”表示注释，编译 器将忽略后面的内容，“///”告诉编译器后 面是 XML 注释，需要适当地处理。 

     【例2-11】 

       声明GetUserName() 方法，将一个表示 手机号码的字符串作为参数传入该方法中， 最终返回用户的姓名。声明后为代码添加文 档注释并完善内容，代码如下：

       上述代码中，名称为 summary、param、 returns 的元素名仅仅是VS 能够识别的一部 分标记，在智能感知功能中，并没有把C# 规范中的所有标记列出来，遗失的部分只能 手工插入。这些手工标记是非常有用的，如 果恰当地设置，对导出成外部说明文件是非 常有帮助的。 

       文档注释的使用非常简单，常用标签只 有上述几个。这是因为大部分项目中的注释 仅仅是给开发人员自己看的，如果想要生成 类似 MSDN 这样的文档，需要了解更多的标签。常见标签及标签说明如表 2-3 所示。 

表 2-3　文档注释常见的几个标签