C# XML文档注释

XML文档注释不仅为每个类、函数添加注释，说明他们的功能和用法，而且与 Visual Stdio 本身的代码智能感知系统无缝集成了。从而编译器便能自动提示XML注释信息，还可以生成我们需要的参考文档。
Visual Stdio 中 输入三个斜杠即“///”该XML文档注释的标记会根据当前内容自动生成。
1．结构与类的XML文档注释
结构与类的XML文档注释在使用方式上是完全一致的，我们只需要在summary标签中描述该类型的用途。
示例001
由于编译器在处理XML文档注释的时候，会把相应的声明一起编译，因此我们不需要在注释文字中再强调这是一个类或是一个结构，只需要描述它的用途。下面的几种描述方式都是比较好的，建议尽量进行套用：
> 表示……
如果该结构或类是真是世界中的某个物体或抽象概念的直接反映，且其名称本身足以让人理解它的主要用途时，可以使用这种表述方式。
如：表示 一幅用于人脸识别的灰度图像。
> 提供……
如果该结构或类更倾向于提供某种功能或服务，或者其本身的抽象概念名称无法清晰表达它的主要用途时，可以使用这种表达方式。
如：提供创建图形缓冲区的方法。
> 包含……
有些类型本身并没有包含功能，它的主要目的就是提供对其它一些工具或对象的访问，此时可以使用这种表达方式。
如：包含所有标准颜色的画笔对象。

在XML 注释中，我们只需要写出这个结构或类是什么，让使用者明白它的用途即可，不必将结构或类的内部的工作方式公布出来，这会破坏类的封装性。毕竟其内部如何工作是设计者的事情，而不是使用者所需要关心的。普通注释的读者是源代码的读者，而 XML文档注释的读者是结构或类的使用者。
仅在两种情况下，我们有必要将内部的工作方式透漏给使用者。
> 一种是，当”多个功能相似的类“并存的时候，其主要区别即在于内部的工作方式。
例如：同样都是表示“集合”的类，一个是用数组实现，一个使用链表实现，一个使用双向链表实现，一个使用哈希表实现等等。如果单独考虑每一个类在注释的时候就没有必要解释其工作方式，而当他们同时存在的时候，就必须将其具体的实现方式公开出来。
> 另一种情况是，如果使用者不知晓内部的某些具体的处理方式，则可能会导致严重的性能问题或者安全问题时需要将其具体的实现方式公开出来。

对于结构与类来说，只有 summary 这一个必备的标签

2．属性的XML文档注释
属性，与结构和类相似，也只有 summary 这一个必须的XML文档注释标签，用于描述这个属性的作用
示 例002
在措辞上，如果属性即可读又可写，那么以“获取或设置……”的方式进行描述；如果属性为只读，那么可以使用“获取……”的描述方式；有时，以“获取（或设置）”开头可能在语言组织上会发生困难，这通常发生在 bool 类型或枚举类型的属性上。此时则可以使用“获取（或设置）一个值，该值表示……”的方式进行阐释。

3．方法的XML文档注释
相比而言，与方法相关的XML文档注释要丰富的多。不但需要 summary 标签添加总体描述，还要用 param 标签为每个参数进行详细的说明，并用 returns 标签描述函数的返回值
示 例003
由于方法通常总是为了进行某种操作，因此在为其添加XML文档注释的 summary 标记时，只需要采用动宾结构的短语对其功能进行描述即可。
如：“在指定路径中创建文件”。
如果方法的主要目的是为了获取某个特定的值，那么请使用“返回……”的句式，避免使用“获取”一词，以与属性的描述相区分。
如：返回指定路径字符串的文件名和扩展名。
方法可能会带有参数，那么应当使用 param 标记为每个 param 标记为每个参数添加XML文档注释。它的内容将直接反映在智能感知系统中，向开发人员作出提示。
示例004
在为参数书写XML文档注释时，要采用偏正结构的短语清晰地描述该参数在整个函数方法中的功能及影响，不要从参数名称的字面上进行描述，那样可能无法提供真正有意义的内容。
对于有返回值的方法，我们必须使用 returns 标记详细解释其所有可能的返回值，以及它们代表的含义。很多情况下，方法除了正常的返回值之外，还会出现异常情况下的返回值。二后者则是我们真正要描述的，需要加以说明，这里需要注意一点：c#编程可能调用的组件不是c#编写的程序，由于不同语言之间的差异性，我们在书写XML文档注释的时候，应避免写入与具体语言相关的信息。

4．构造函数的XML文档注释
构造函数与方法的形式类似，XML文档注释的使用方法也基本相同。在描述上，可以采用一些模式化的表达方式。
> 初始化……类的新实例。
对于没有参数限定的构造函数来说，这种表达方式是最简单的。
> 使用指定的……初始化……类的实例。
当构造函数需要参数时，且该参数是起某种限定作用（通常是对某个属性的直接设置）时，即可使用这种形式的描述。
例如：“使用指定的表名初始化 System.Data.DataTable 类的新实例”。
>基于……初始化……类的实例。
当构造函数需要参数，而该参数提供的是核心组件，整个类的一切都是围绕该组件工作或是对它的进一步包装时，建议使用此种描述。
例如：“基于所提供的流，用 UTF-8 作为字符串编码来初始化 System.IO.BinaryWriter 类的新实例“。
当函数有重载时，应采用梗详尽的说明，尽量说明各个重载之间的差异。

5．事件的XML文档注释
事件成员自身只需要通过 summary 标记添加总体描述即可，建议严格地使用“当……时发生”的句式。
示例005

6．枚举类型的XML文档注释
对于枚举类型来说，除了要给枚举类型本身添加 summary 描述之外，还要为每个枚举值添加 summary 描述。
示例006

7．泛型的XML文档注释
与普通类型相比，泛型要多出一个或多个类型参数。添加XML文档注释的方式也很简单，只需要在原有的基础上添加一个 typeparam 标记即可，表述上可采用“……的类型”的句型。
示例007

8．其它标记
如果在编译时打开了编译XML文档注释功能的话，那么之前介绍的那些标记与用法，都会在编译时进行语法检查。假如某个公开的类型或成员缺少 summary 标记，或者是缺少某个参数的返回值的注释，编译器都会给出警告信息。除此之外，还有一些标记不会经过任何语法检查，但仍然有重要的作用。
当你需要进行篇幅较长的解释说明的时候，summary 标记显然是不合适的，它应该包含那些精炼的定义式说明。如果你希望想别人多提供一些信息的话，可以选择在 remarks 标记中。你还可以使用 example 标记添加示例，用 code 标记加入各种代码。
当我们在XML注释文档中需要对某个类型进行引用的时候，不要直接写出类型的名称，而应通过 see 标记进行引用，这样编译器就可以将其识别为一个类型，以便在最终形成的文档中将其转换为链接或其他需要的形式。“see”标记只需要一个“href”属性，其值为类型的名称。
示例008
当需要引用的类型为泛型时，需要注意一点，因为c#中标记泛型类型参数的尖括号 在XML中属于特殊字符，我们需要按照XML的规则将“<”和“>”分别改写为“&lt;”和“&gt;”。
相似地，当需要引用某个参数的名称时，也不要直接书写，而应该使用 paramref 标记进行引用，将参数名作为 name 属性的值写入。而对泛型类型参数的引用，应使用 typeparamref 标记
当某个成员可能抛出异常时，应使用 exception 标记将可能抛出的异常类型逐一列出，并解释抛出异常的主要原因。

总的来说，如果多看看 MSDN 自身的类库参考，你会发现其实XML文档注释最终形成的就是这样的结果。MSDN本身就是一个很好的XML文档注释的范例，我们可以在实践的过程中不断的学习。

本文参考《更锋利的c#代码》