C# 文档和注释

引言

我们大多数人都曾经历过更新文档的恐惧。C# 和 Visual Studio .NET (VS.NET) 让我们能够在同一个文件中维护代码和文档，这使得整个过程变得容易得多。VS.NET 通过从代码中获取特殊标记和结构化的注释，并将它们构建成一个 XML 文件来实现这一点。然后，这个 XML 文件可以用于生成各种形式的人类可读文档，包括网页、MSDN 风格的文档以及代码窗口中的 Intellisense。

配置 XML 注释

VS.NET 通过从代码中获取特殊标记和结构化的注释，并将它们构建成一个 XML 文件来生成 XML 注释。然后，这个 XML 文件可以用于生成各种形式的人类可读文档，包括网页、MSDN 风格的文档以及代码窗口中的 Intellisense。你需要做的第一件事是为你的 VS.NET 项目启用 XML 注释功能。

1. 在解决方案资源管理器中右键单击项目并选择“属性”。
2. 在属性对话框中，双击“配置属性”节点。
3. “生成”节点应该已经被选中，并且你应该能够在“输出”下看到“XML 文档文件”条目。你必须在这里输入将包含注释数据的 XML 文件的名称。你可以随意命名文件，但为了与 XML 注释的所有功能兼容，它应该采用 MyAssemblyName.Xml 的形式，例如，Adjuster.BusinessServices.dll 有一个相关的 XML 文件，名为 Adjuster.BusinessServices.Xml

启用此功能后，每次生成项目时，你的 XML 注释数据文件都会被重新生成。生成文件时发生的任何问题都不会阻止生成，但会在 VS.NET 任务列表中标记出来。假设你没有将编译警告设置为错误。

VS.NET 任务列表标记 XML 注释错误。

启用此功能后，你就可以在你的过程“头”中使用特殊的 XML 标签了。要开始使用，将光标放在过程定义正上方的那一行。在那里，按三次“/”键，这将自动在你的代码中插入一个摘要标签。如果该过程有任何参数，现在应该为每个参数都有一个 param 标签。

/// <summary>
/// 
/// </summary>
/// <param name="data"></param>
public void SaveData(ref DataSet data)
{

}

上面的 SaveData 代码是默认插入的。

/// <summary>
/// Connects to the database and attempts to apply 
/// all adds, updates and deletes
/// </summary>
/// <param name="data">a dataset, passed by reference, 
/// that contains all the 
/// data for updating>/param>
public void SaveData(ref DataSet data)
{

}

这段 SaveData 代码是在我添加了描述例程在摘要标签中做什么以及数据参数是什么的注释之后。这个非常简单的操作足以提供基本文档，包括与 .NET Framework 程序集提供的相同的 Intellisense。

仅从这个功能就可以清楚地看出 XML 注释是多么有用。当你引用一个启用了 XML 注释的 .NET 项目时，我们前面命名的 XML 文档文件会与二进制文件一起复制到当前项目的 \bin 目录。这使你可以在程序集之间获得 Intellisense。

摘要标签是最基本的标签。下面的列表是 VS.NET 当前支持的完整集合。标有 * 的是我认为最有用的标签，也是我们将在以下示例中处理的标签。

• c
c 标签提供了一种方法，可以指示描述中的文本应标记为代码。使用 code 标签表示多行代码。

• code*
  code 标签提供了一种方法，可以指示多行代码。使用 <c> 标签表示描述中的文本应标记为代码。

• 示例*
  example 标签允许你指定如何使用方法或其他库成员的示例。通常，这会涉及到使用 code 标签。

• exception*
  exception 标签允许你指定类可以抛出哪些异常。

• include
include 标签允许你引用另一个文件中的注释，这些注释描述了源代码中的类型和成员。这是将文档注释直接放在源代码文件中的替代方法。

• para
para 标签用于标签内部，例如 <remarks> 或 <returns>，它允许你为文本添加结构。

• param*
  param 标签应用于方法声明的注释中，以描述方法的参数之一。

• paramref
paramref 标签提供了一种方法，可以指示某个词是参数。XML 文件可以被处理以某种独特的方式格式化此参数。

• permission*
  permission 标签允许你记录成员的访问权限。System.Security.PermissionSet 允许你指定对成员的访问权限。

• remarks*
  remarks 标签是你可以指定有关类或其他类型的概述信息的地方。<summary> 是你可以描述类型成员的地方。

• returns
returns 标签应用于方法声明的注释中，以描述返回值。

• see
see 标签允许你指定文本中的链接。使用 <seealso> 来指示你可能希望出现在“另请参阅”部分中的文本。

• seealso*
  seealso 标签允许你指定你可能希望出现在“另请参阅”部分中的文本。使用 <see> 来指定文本中的链接。

• summary*
  summary 标签应用于描述类型的成员。使用 <remarks> 来提供有关类型本身的信息。

• value*
  value 标签允许你描述属性。请注意，当你在 Visual Studio .NET 开发环境中通过代码向导添加属性时，它会为新属性添加一个 <summary> 标签。然后你应该手动添加一个 <value> 标签来描述属性所代表的值。

MSDN 风格文档和 NDOC

我们已经将 Intellisense 格式发挥到了极致，但我们还可以使用 MSDN 风格的文档做更多的事情。VS.NET 附带了一个工具，你可以在“工具|构建注释网页…”中找到它，它将从源文件中获取你的 C# XML 注释并生成链接的 HTML 文件。这个是开箱即用的，所以不应该完全忽视。但是，如果你想创建易于使用、有帮助、相互引用且美观的文档，那么我强烈推荐免费的开源工具 NDoc。下面的屏幕截图来自 NDoc 生成的编译帮助文件，是它所能产生的质量的一个示例。

下面的两个例程将显示我们之前看到的许多 XML 注释标签的正确用法。exception 标签的 cref 属性用于交叉引用异常类型。此属性也用于 seealso、permission 和 see 标签中以引用类型。该类型必须在当前编译环境中可用。编译器会检查引用的类型是否存在，并将相关数据传递给输出 XML。

/// <summary>
/// Gets or sets the age of the person involved in the accident
/// </summary>
/// <value>Age of the claimant.</value>
/// <remarks> The value must be numeric.
/// </remarks>
/// <exception cref="System.ApplicationException">Thrown when a non-
/// numeric value is assigned.</exception>
public string Age
{
}

这个 Age 属性经过 NDoc 处理后将生成这个。

我已将注意力集中在图片中的区域及其对应的 XML 注释标签上。

/// <summary>
/// Connects to the database and attempts to apply all adds, 
/// updates and deletes
/// </summary>
/// <seealso cref="Adjuster.BusinessServices.Accident"/> 
/// <param name="data">a dataset, passed by reference, 
/// that contains all the 
/// data for updating</param>
/// <example> This sample shows how to call the SaveData 
/// method from a wireless device.
/// <code>
/// 
///AccidentCRUD accCRUD = new Adjuster.BusinessServices.AccidentCRUD();
///accCRUD.SaveData(ref ds);
///
///</code>
///</example>
///<permission cref="System.Security.PermissionSet">Everyone 
///can access this method.</Permission>
public void SaveData(ref DataSet data)
{
}

这个 SaveData 方法经过 NDoc 处理后将生成这个

我再次将注意力集中在图片中的区域及其对应的 XML 注释标签上。“另请参阅”部分中的 Accident 交叉引用是我添加的唯一一个。默认情况下，NDoc 会为父类、父类的成员和父类的命名空间添加交叉引用。

结合 NDoc 和 VS.Net & C# 生成这些注释的能力，你可以在非常接近代码的级别上获得出色的技术文档，以至于它绝对没有任何借口不实事求是。