C#中XML注释的用途是什么？

Question

在C#中，与单行注释和多行注释相比，XML注释的作用是什么？

i.Single line
Eg:
//This is a Single line comment

ii. Multiple line (/* */)
Eg:
 /*This is a multiple line comment
We are in line 2
Last line of comment*/

iii. XML Comments (///).
Eg:
/// summary;
///  Set error message for multilingual language.
/// summary

- Nayana Adassuriya

---

http://msdn.microsoft.com/en-us/library/z04awywx.aspx - L.B

Answer 1

从XML文档注释（C#编程指南）：

使用 /doc 选项进行编译时，编译器将查找源代码中的所有XML标记并创建一个XML文档文件。

同时这些XML注释也被Visual Studio用于智能感知：

/// <summary>
///  This class performs an important function.
/// </summary>
public class MyClass{}

当您编写代码或将光标悬停在具有XML注释的成员上时，它会为您提供良好的提示：

注意：通常您应仅向公开可见的类型或成员添加XML注释。如果成员是内部或私有的，则是好的但不是必需的。有一个很好的工具GhostDoc（作为Visual Studio的扩展程序可用），可以从类型或成员名称生成XML注释。检查一下您的命名是否良好，如果生成的注释不清晰，则应改进成员的名称。

我还建议尽可能少使用简单（非XML）注释。因为注释是代码重复的一种形式 - 它重复了您已经在代码中拥有的信息。这里有两个问题：

• 您的代码不够清晰，应改进它（重命名，提取类别或成员）而不是添加注释。
• 当代码发生更改时，注释通常保持不变（程序员比较懒）。所以随着时间的推移，注释变得过时和混乱。

好的注释应描述您编写代码的原因，而不是复制代码正在做什么的信息。

- Sergey Berezovskiy

Answer 2

XML注释以///开头，将被IntelliSense捕捉到，并在从其他地方查看时显示在弹出窗口中。有一个 MSDN页面 解释它的工作原理。

它们还将被许多构建文档文件等工具捕获。

- David Božjak

Answer 3

从MSDN文档中得知：

当您使用/doc选项编译时，编译器将搜索源代码中的所有XML标记并创建一个XML文档文件。要基于编译器生成的文件创建最终文档，可以创建自定义工具或使用像Sandcastle这样的工具。

http://msdn.microsoft.com/en-us/library/b2s063f7.aspx

- Mike Chamberlain

Answer 4

XML注释用于构建API文档，这些文档可以被外部工具读取。IntelliSense也会读取这些注释，并在您输入代码时使用其内容在辅助工具提示中显示代码文档（以及在文档窗口中显示）。

编译器（可选地）提取所有这些注释并将它们放入与您的程序集相邻的单独的独立XML文件中；这个文件可以被解析。

这个想法是为了有一个类似JavaDoc的东西。不幸的是，微软未能提供一个主流成熟的工具来实现这一点。

- TypeIA

Answer 5

当您创建 DLL 程序集时，XML 注释为该 DLL 的用户提供有关函数或其他内容的一些信息

- TC Alper Tokcan

Answer 6

所有编程语言通常都允许特殊注释。这些注释可以被解析，从而创建代码的自动文档。许多库都是以这种方式进行记录。

在C#中，Microsoft提供了这些工具，并且您可以使用XML注释声明该注释应由文档处理过程接收 - 如果您已经设置了一个。这些注释也会被自动完成所捕获。

另请参见doxygen、JavaDoc等其他语言的实现。请参阅相关问题生成MSDN风格文档的好替代品

- Peter