2.12.2 XML文档说明

http://book.51cto.com 2007-12-11 20:43 Christian Nagel等著李铭译黄静审校清华大学出版社我要评论(0)

摘要：《C#2005&.NET_3.0高级编程》(第5版)第二章介绍C#的基础知识。本文主要介绍的是XML文档说明
标签：C# .NET XML 文档 C#2005&.NET_3.0高级编程

2.12.2 XML文档说明

如前所述，除了C风格的注释外，C#还有一个非常好的功能，本章将讨论这一功能。根据特定的注释自动创建XML格式的文档说明。这些注释都是单行注释，但都以3个斜杠(///)开头，而不是通常的两个斜杠。在这些注释中，可以把包含类型和类型成员的文档说明的XML标识符放在代码中。

编译器可以识别表2-10所示的标识符。

表 2-10

标识符	说明
	把行中的文本标记为代码，例如int i = 10;
	把多行标记为代码
	标记为一个代码示例
	说明一个异常类(编译器要验证其语法)
	包含其他文档说明文件的注释(编译器要验证其语法)
	把列表插入到文档说明中
	标记方法的参数(编译器要验证其语法)
	表示一个单词是方法的参数(编译器要验证其语法)
	说明对成员的访问(编译器要验证其语法)
	给成员添加描述
	说明方法的返回值
	提供对另一个参数的交叉引用(编译器要验证其语法)
	提供描述中的“参见”部分(编译器要验证其语法)
	提供类型或成员的简短小结
	描述属性

要了解它们的工作方式，可以在上一节的MathLibrary.cs文件中添加一些XML注释，并称之为Math.cs。我们给类及其Add方法添加一个

元素，也给Add方法添加一个元素和两个元素：

// Math.cs
namespace Wrox.ProCSharp.Basics
{

   ///
   ///   Wrox.ProCSharp.Basics.Math class.
   ///   Provides a method to add two integers.
   ///
   public class Math
   {
      ///
      ///   The Add method allows us to add two integers
      ///
      ///Result of the addition (int)
      ///First number to add
      ///Second number to add
      public int Add(int x, int y)
      {
         return x + y;
      }
   }
}

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

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

如果XML注释没有生成格式正确的XML文档，编译器就生成一个错误。

上面的代码会生成一个XML文件Math.xml，如下所示。



   
      Math
   
   
      
         
            Wrox.ProCSharp.Basics.Math class.
            Provides a method to add two integers.
         
      
      
         
            The Add method allows us to add two integers.
         
         Result of the addition (int)
         First number to add
         Second number to add