认识XML文档注释的标记

在编写代码时，为类型以及类型的成员添加文档注释是一个好的习惯。C#以及其他.NET语言的编译器能够将文档注释处理成一个XML文件，再利用一些工具（如Sandcastle和已经死去的NDoc），还能把文档注释制作成帮助文档。所以，有必要学习一下文档注释推荐使用的标记。

理论上，可以使用任意的标记，不过在MSDN中，推荐使用以下的文档注释标记：

• <c>
• <code>
• <example>
• <exception>
• <include>
• <list>
• <para>
• <param>
• <paramref>
• <permission>
• <remarks>
• <returns>
• <see>
• <seealso>
• <summary>
• <typeparam>
• <typepraramref>
• <value>

有些标记比较简单，可能已经被大家所熟悉和使用了，比如<summary>。而且如果使用了开发工具的话（如Visual Studio），还能自动生成标记以及属性，非常方便。

除了这些标记之外，其他语言，如VB.NET，和一些文档生成工具，如NDoc和Sandcastle等，还补充了一些标记：

• <event>
• <exclude>
• <filterpriority>
• <note>
• <overloads>
• <preliminary>
• <threadsafety>

这些补充的标记能够帮助文档生成工具在生成文档的时候，提供更丰富的内容。

参考资料：

• MSDN：Recommended Tags for Documentation Comments
• XML Documentation Comments Guide