2.12 使用注释
2.12.1 源文件中的内部注释
在本章开头提到过，C#使用传统的C风格注释方式：单行注释使用// ...，多行注释使用 /* ... */：
// This is a single-line comment
/* This comment
spans multiple lines */
单行注释中的任何内容，即//后面的内容都会被编译器忽略。多行注释中/* 和 */之间的所有内容也会被忽略。显然不能在多行注释中包含*/组合，因为这会被当作注释的结尾。
实际上，可以把多行注释放在一行代码中：
Console.WriteLine(/*Here's a comment! */ "This will compile");
像这样的内联注释在使用时应小心，因为它们会使代码难以理解。但这样的注释在调试时是非常有用的，例如，在运行代码时要临时使用另一个值：
DoSomething(Width, /*Height*/ 100);
当然，字符串字面值中的注释字符会按照一般的字符来处理：
string s = "/* This is just a normal string */";
2.12.2 XML文档说明
如前所述，除了C风格的注释外，C#还有一个非常好的功能，本章将讨论这一功能。根据特定的注释自动创建XML格式的文档说明。这些注释都是单行注释，但都以3个斜杠(///)开头，而不是通常的两个斜杠。在这些注释中，可以把包含类型和类型成员的文档说明的XML标识符放在代码中。
编译器可以识别表2-10中所示的标识符。
表 2-10
|
标 识 符 |
说 明 |
|
<c> |
把行中的文本标记为代码，例如<c>int i = 10;</c> |
|
<code> |
把多行标记为代码 |
|
<example> |
标记为一个代码示例 |
|
<exception> |
说明一个异常类(编译器要验证其语法) |
|
<include> |
包含其他文档说明文件的注释(编译器要验证其语法) |
|
<list> |
把列表插入到文档说明中 |
|
<param> |
标记方法的参数(编译器要验证其语法) |
|
<paramref> |
表示一个单词是方法的参数(编译器要验证其语法) |
|
<permission> |
说明对成员的访问(编译器要验证其语法) |
|
<remarks> |
给成员添加描述 |
|
<returns> |
说明方法的返回值 |
|
<see> |
提供对另一个参数的交叉引用(编译器要验证其语法) |
|
<seealso> |
提供描述中的“参见”部分(编译器要验证其语法) |
|
<summary> |
提供类型或成员的简短小结 |
|
<value> |
描述属性 |
要了解它们的工作方式，可以在上一节的MathLibrary.cs文件中添加一些XML注释，并称之为Math.cs。我们给类及其Add方法添加一个<summary>注释，也给Add方法添加一个<returns>元素和两个<param>元素：
// Math.cs
namespace Wrox.ProCSharp.Basics
{
///<summary>
/// Wrox.ProCSharp.Basics.Math class.
/// Provides a method to add two integers.
///</summary>
public class Math
{
///<summary>
/// The Add method allows us to add two integers
///</summary>
///<returns>Result of the addition (int)</returns>
///<param FTEL="x">First number to add</param>
///<param FTEL="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:Math.xml Math.cs
如果XML注释没有生成格式正确的XML文档，编译器就生成一个错误。
上面的代码会生成一个XML文件Math.xml，如下所示。
<?xml version="1.0"?>
<doc>
<assembly>
<name>Math</name>
</assembly>
<members>
<member FTEL="T:Wrox.ProCSharp.Basics.Math">
<summary>
Wrox.ProCSharp.Basics.Math class.
Provides a method to add two integers.
</summary>
</member>
<member FTEL=
"M:Wrox.ProCSharp.Basics.Math.Add(System.Int32,System.Int32)">
<summary>
The Add method allows us to add two integers
</summary>
<returns>Result of the addition (int)</returns>
<param FTEL="x">First number to add</param>
<param FTEL="y">Second number to add</param>
</member>
</members>
</doc>
注意，编译器为我们做了一些工作——它创建了一个<assembly>元素，并为该文件中的每个类型或类型成员添加一个<member>元素。每个<member>元素都有一个name特性，其中包含成员的全名，前面有一个字母表示其类型："T:"表示这是一个类型，"F:" 表示这是一个字段，"M:" 表示这是一个成员。