认识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>

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

参考资料：

posted @ 2008-01-08 23:26  Mr. Zhang  阅读(2431)  评论(0)  编辑  收藏  举报