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:"表示一个成员。