C# XML文档

C#中的注释有三种：

1、单行注释：//

2、多行注释：/* */

3、文档注释：///

前两种是 C、C++、Java中有的，第三种是C#特有，虽然///也是单行注释，但是它可以创建XML格式的文档说明。

MSDN提供了建议的文档注释标记

要了解它的工作方式，可以在之前的MathLibrary.cs 文件中添加一些XML注释。我们给类及其 Add()方法添加一个 <summary> 元素，也给 Add() 方法添加一个 <returns> 元素和两个 <param> 元素：

// MathLib.cs
namespace Wrox
{
///<summary>
/// Wrox.Math class.
/// Provides a method to add two integers.
///</summary>
public class MathLib
{
///<summary>
/// The Add method allows us to add two integers.
///</summary>
///<returns>Result of the addition (int)</returns>
///<param name="x">First number to add</param>
///<param name="y">Second number to add</param>
public int Add(int x, int y)
{
return x + y;
}
}
}

C#编译器可以把XML元素从特定的注释中提取出来，并使用它们生成一个 XML 文件。要让编译器为程序集生成 XML 文档，需在编译时指定 /doc 选项，后跟要创建的文件名：

csc /t:library /doc:MathLibrary.xml MathLibrary.cs

下面是生成的 XML 文档：

<?xml version="1.0"?>
<doc>
<assembly>
<name>MathLibrary</name>
</assembly>
<members>
<member name="T:Wrox.MathLib">
<summary>
Wrox.Math class.
Provides a method to add two integers.
</summary>
</member>
<member name="M:Wrox.MathLib.Add(System.Int32,System.Int32)">
<summary>
The Add method allows us to add two integers.
</summary>
<returns>Result of the addition (int)</returns>
<param name="x">First number to add</param>
<param name="y">Second number to add</param>
</member>
</members>
</doc>

注意，编译器自动完成了一些工作--它创建了一个 <assembly> 元素，并为该文件的每个类型或类型成员添加一个 <member> 元素，每个 <member> 元素都有一个 name 特性，该特性的值是成员的全名，前面有一个字母，含义如下："T:"表示一个类型，"F:"表示一个字段，"M:"表示一个成员。