9.17.3　XML文档注释

XML文档注释^[1]是和文档有关的注释，它允许我们为代码创建文档。该文档可由专门的程序从源代码中读取，并根据需要生成HTML文件或者CHM帮助文件等。

添加XML文档注释非常简单，只需要在要添加的程序对象上连续输入3个斜杠即可，然后Visual Studio 2010会自动生成大部分的注释文本，我们只需在其中添加对各注释元素的说明即可，如代码清单9-50所示。

代码清单9-50　XML文档注释示例

///＜summary＞

///演示异步调用的代码示例

///＜/summary＞

class AsynchronousSample

{

//……

}

当我们连续输入3个斜杠（/）时，一个注释框架会自动产生，如下所示：

///＜summary＞

///

///＜/summary＞

如果被注释的程序元素，假设是一个方法，具有参数和返回值，那么自动生成的注释框架也会包含这些内容，如代码清单9-51所示。

代码清单9-51　另一个XML文档注释

///＜summary＞

///判断是否相等

///＜/summary＞

///＜param name="x"＞对象x＜/param＞

///＜param name="y"＞对象y＜/param＞

///＜returns＞相等返回true，否则返回false＜/returns＞

public bool Equals（Product x，Product y）

{

if（Object.ReferenceEquals（x，y））return true；

if（Object.ReferenceEquals（x，null）||Object.ReferenceEquals（y，null））

return false；

return x.Code==y.Code＆＆x.Name==y.Name；

}

截至现在，我们已经见过XML文档注释中的＜summary＞、＜param＞、＜returns＞等标记，这些标记的含义是什么呢？接下来将对这些标记进行介绍，如表9-10所示。

[1]XML文档注释不是元数据，并不包括在编译的程序集中，因此无法通过反射对它们进行访问。