C# 和 XML 源代码文档

MichaelElliott

4.83/5 (317投票s)

2005 年 7 月 23 日

CPOL

18分钟阅读

1051413

演示了如何使用 C#.NET 的 XML 源代码文档生成专业的、索引化的和可搜索的源代码文档。

引言

经过多年企业级软件开发和咨询的经验，我深刻认识到良好的源代码文档的重要性。几年前，当我开始使用 Visual Studio .NET beta 1 的第一个版本，并发现 C# 提供了内联 XML 代码文档的内置支持时，我感到非常激动。

在我成立自己的专业服务咨询公司后，让我的客户能够支持、维护和扩展我公司代表他们生产的任何软件变得更加重要，而扎实、全面的源代码文档是实现这一目标的步骤之一。

在 Visual Studio .NET 的所有版本中，只有 C# 提供了内联 XML 代码文档的内置支持；然而，有几个免费的第三方插件可以用来在 C++, VB.NET 和 J# 中实现 C#.NET 目前提供的相同内联源代码 XML 文档。

对于非 C# 开发者来说，好消息是 Microsoft 在 Visual Studio .NET 2005 中为所有 .NET 语言提供了相同的内联 XML 代码文档支持。

尽管 Visual Studio .NET 提供了生成代码文档报告的内置功能，但我更喜欢使用开源的 NDoc 工具，因此我不会详细介绍如何使用 Visual Studio 生成 .htm 报告，但我将演示如何使用 C#、Visual Studio .NET 2003 和 NDoc 为您的源代码生成集成、可搜索和索引化的源代码文档。

NDoc 不支持 2.0 或更高版本。要使用本文中的详细信息并从源代码文件中的 XML 文档生成源代码文档，您可以使用可以从 http://www.stack.nl/~dimitri/doxygen/ 下载的免费工具。

文章目标

概述 C#.NET 代码文档的内置功能。
概述最常见的 C#.NET XML 文档标签。
演示如何使用 NDoc 生成集成、可搜索和索引化的 API 帮助文件。

请在离开本文之前提供评分/投票。

这是作者唯一获得其免费分享的作品认可的方式。看到帮助过 100,000 多人的文章，但只有不到 200 人费心投票或评分，真是令人 sad。

C# 内置功能

有三种类型的注释标识符用于记录 C# 源代码

标记	示例	描述
双斜杠	`// 注释`	用于注释或备注单行。
斜杠星号	`/* 注释 */`	用于注释或备注多行。
三斜杠	`///`	用于添加内联 XML 文档标记。

  // This is a single line remark or comment
  
  /*
  *  This is line 1 of a comment block
  *  This is line 2 of the comment block
  */
  
  /// <summary>
  ///    This is a sample summary comment 
  ///    using the 'summary' xml tag.
  /// </summary>
  public void GetLoginAttempts( string userId ) { … }

C# 提供了几个 XML 标签，可以放置在源代码文件内部，用于记录代码，Microsoft 在 Visual Studio .NET 帮助文件中对这些标签进行了很好的文档记录。一旦开发者使用 XML 标签记录了他们的源代码，他们就可以使用 NDoc 生成集成式的 .chm 文件，其中包含源代码文档。

尽管上面的描述和本文可能使用“注释”一词，但 XML 标签用于生成外部源代码文档。这与传统的代码注释不同，因为生成的文档可以作为 API（应用程序编程接口）文档分发。

在讨论 NDoc 和如何生成 .chm 文件之前，让我们先研究一下如何使用 XML 标签来 instrument C# 源代码，并更详细地讨论一些可用的 XML 文档标签。

XML 文档标签

XML 文档标签用于记录类及其高级特性，如构造函数、析构函数、方法、属性、字段、委托、枚举、事件和其他特性。

Visual Studio .NET 识别 /// 标记，并在指示时为开发者插入常用、合适的标签。开发者通过在目标特性上方键入 /// 标记来指示 Visual Studio .NET 插入这些标签。Visual Studio 将插入的常用标签是：summary、param（如果适用）和 returns（如果适用）。

图 1 展示了一个标准的在开发者指示 Visual Studio 在目标特性上方键入 /// 来插入 XML 标签之前的状态和之后的状态。

  // Figure 1

  // Before:

  public bool StringIsValid( string validateMe ) { … }


  // After the developer types 3 slashes (///) 
  // above the method signature:

  /// <summary>
  /// 
  /// </summary>
  /// <param name="validateMe"></param>
  /// <returns></returns>
  public bool StringIsValid( string validateMe ) { … }

现在您知道如何提示 Visual Studio .NET 插入 XML 标签了，让我们来讨论一些常用标签及其用法。由于这些标签是 XML，因此它们需要是“格式良好”的。至少从需要确保提供正确的结束标记并根据需要使用单引号或双引号的意义上来说。

在下表中的链接会显示或显示其他信息时，我指的是生成的 .chm 文档文件中的链接，而不是 Visual Studio .NET 中的链接。反之，当我提到 IntelliSense 或客户端时，信息将在 Visual Studio .NET 中显示。

请注意，本文并未涵盖 C# 和 Visual Studio .NET 支持的所有 XML 标签，而是涵盖了最常用的标签。

Tag	用法	描述
`summary`	`<summary>您的摘要</summary>`	提供类型或成员的简短描述。在 `summary` 标签的开始和结束标签之间键入的文本会在您将鼠标悬停在类型上时，在 Visual Studio 的 IntelliSense 中显示。
`param`	`<param name='name'>描述。</param>` 'name' 必须用单引号括起来。	提供相关参数的描述。在 `param` 标签的开始和结束标签之间键入的文本将在编写客户端代码时显示。
`returns`	`<returns>描述。</returns>`	提供方法向客户端返回内容的描述。
`remarks`	`<remarks>您的备注。</remarks>`	提供关于类型或成员的更详细信息，这些信息对于使用该类型的人来说可能很重要。这是记录类型是否线程安全等事项的好地方。
`para`	`<para>您的文本。</para>`	允许您通过插入或包装段落内的片段来控制文档输出的格式。您将把 `para` 标签嵌套在其他标签内。
`c`	`<c>您的代码示例。</c>`	表示一段简短的代码。您将使用 `c` 标签来吸引对最终文档中特定词语、短语或代码的注意。您将把 `c` 标签嵌套在其他标签内。
`paramref`	`<paramref name="name"/>` 包含结束标签，并且必须在参数的“name”周围使用双引号。	允许您将单词链接到同名的参数。 `paramref` 标签会导致包含的单词在最终文档中链接到 `param` 描述。 `<param name='myParm'>`描述`</param>` `<remarks>`确定 `<paramref name=”myParm”/>` 是 `<c>`null`</c>` 还是 `<c>`empty`</c>`。`</remarks>` 您会发现这是最常用的标签之一。
`see`	`<see cref="member"/>` 包含结束标签，并且必须在链接的“member”周围使用双引号。	允许您创建对类中可用的任何类型、成员或字段的引用，而不会导致编译错误（包括 .NET 类型和自定义类型）。这个标签一个非常好的集成功能是，这些引用会直接集成到 Visual Studio 帮助系统中。 `<returns>`一个 `<see cref=”System.String”/>` 包含用户的唯一标识符。`</returns>` 当您单击 String 上的链接时，您将看到 `String` 类型的实际 Microsoft 文档。
`exception`	`<exception cref="member">` 包含结束标签，并且必须在链接的“member”周围使用双引号。	允许您记录成员将抛出的异常类型。 `<exception cref="ArgumentException">` 如果 `<paramref name="firstName"/>` 为 `<c>`empty`</c>`。`</exception>` 当您单击成员链接时，您将看到异常类型的实际 Microsoft 文档。方法使用多个 `<exception>` 标签并不罕见。
`code`	`<code>您的代码示例。</code>`	`code` 标签类似于 `<c>` 标签，但它旨在说明实际的代码使用示例。 `code` 标签通常包含在 `<example>` 标签集中（见下文）。将 `code` 标签与 `example` 标签结合使用。
`示例`	`<example>您的示例。</example>`	提供了一种说明代码示例的方法。通常，`example` 标签集将包含 `code` 标签集。将 `example` 标签与 `code` 标签结合使用。

现在您已经掌握了最常用的标签，让我们来讨论源代码文档。

记录您的代码

源代码文档记录应该是开发过程的标准部分。如果您养成在编写代码时记录代码的习惯，您会发现自己可以比先编写代码然后尝试在以后进行文档记录更快地生成完整的文档代码。我发现，如果我在编写代码时就对其进行文档记录，其文档记录时间比我尝试在之后回去进行文档记录要少 50%。

如果您不习惯完全记录您的源代码，您将不得不习惯于您的 .cs 文件会更长，这会导致您滚动更多；然而，我发现的一个技巧是利用 .NET 的 region 功能来减少这种副作用。

尽管本文不涉及，但您可以将 XML 文档写在外部文件中，并使用 <include> 标签将外部文件链接到您的源代码。无论您的注释是在实际源代码 .cs 文件中还是在“include”文件中，您都可以生成相同的文档。

我尽量确保为我源代码中的所有类型及其成员提供文档。尽管具体的实现决定了使用的标签，但我尽量为相关类型提供至少以下 XML 标签（我记录所有成员，无论其范围或访问修饰符如何）

类型/成员	标签
类	`Summary`、`Remarks` 和 `Example`（如果需要）
方法	`Summary`、`Remarks`、`Param`、`Returns` 和 `Exception`
属性	`Summary`、`Value`、`Remarks` 和 `Exception` 在 `summary` 标签中，指明属性是读/写、只读还是只写。 `<summary>`获取或设置用户的名字。`<summary>` 如果您将此信息添加到 `summary` 标签中，开发人员在消费该库时，可以在 IntelliSense 中看到此信息……非常有帮助。
字段	`摘要`
常量	`Summary` 和 `Value` 尽管有一个特定的 `Value` 标签，但在 `Summary` 标签中指明常量的`值`，您将能够在开发过程中在 IntelliSense 中看到分配的值。我发现这使我无需去查找常量来确定分配的值，因为我只需将鼠标悬停在常量上，IntelliSense 就会为您完成工作（您一定要试试这个）。 `<summary>`访问所有状态的存储过程。值：MyStoredProcName `<summary>`
委托（Delegates）	`Summary`、`Remarks`、`Param` 和 `Returns`

图 2 展示了一个使用本文讨论的所有 XML 标签记录的简短类。

  // Figure 2

  namespace Mike.Elliott.Articles.XML.Documentation
  {
      using System;

      /// <summary>
      ///   The <c>DocumentationSample</c> type 
      ///   demonstrates code comments.
      /// </summary>
      /// <remarks>
      ///   <para>
      ///     The <c>DocumentationSample</c> type 
      ///     provides no real functionality; 
      ///     however, it does provide examples of 
      ///     using the most common, built in 
      ///     <c>C#</c> xml documentation tags.
      ///   </para>
      ///   <para>
      ///     <c>DocumentationSample</c> types are not 
      ///      safe for concurrent access by 
      ///     multiple threads.
      ///   </para>
      /// </remarks>
      public class DocumentationSample
      {
          /// <summary>
          ///   Initializes a new instance of a 
          ///   <c>DocumentationSample</c> type.
          /// </summary>
          /// <example>The following is an example of initializing a 
          /// <c>DocumentationSample</c> type:
          ///   <code>
          ///     // Create the type.
          ///     DocumentationSample ds = new DocumentationSample();
          ///     
          ///     if ( null == ds )
          ///       return;
          ///       
          ///     return ds.MyMethod( “someString” );
          ///   </code>
          /// </example>
          public DocumentationSample() { … }

          /// <summary>Causes something happen.</summary>
          /// <param name="someValue">
          ///   A <see cref="String"/> type representing a value.
          /// </param>
          /// <exception cref="ArgumentNullException">
          ///   if <paramref name="someValue"/> is <c>null</c>.
          /// </exception>
          /// <exception cref="ArgumentException">
          ///   if <paramref name="someValue"/> is <c>empty</c>.
          /// </exception>
          /// <returns><paramref name="someValue"/> 
          ///   as passed in.</returns>
          public string MyMethod( string someValue )
          { 
              if ( null == someValue )
                  throw new ArgumentNullException( "Your message." );

              if ( 0 >= someValue.Length )
                  throw new ArgumentException( "Your message." );

              return someValue;
          }
      }

现在让我们分解一下源代码。

分解

让我们看一下代码片段以及 XML 文档的使用方式。本文前面提供的标签使用表中的每个 XML 标签都得到了涵盖。

图 3 展示了 <summary>、<c>、<remarks> 和 <para> XML 文档标签的使用。

  // Figure 3

  /// <summary>The <c>DocumentationSample</c> type 
  /// demonstrates code comments.</summary>
  /// <remarks>
  ///     <para>
  ///         The <c>DocumentationSample</c> type 
  ///         provides no real functionality; 
  ///         however, it does provide examples of 
  ///         using the most common, built in 
  ///         <c>C#</c> code comment xml tags.
  ///     </para>
  ///     <para><c>DocumentationSample</c> types are not 
  ///           safe for access by concurrent threads.</para>
  /// </remarks>
  public class DocumentationSample { … }

图 4 展示了 <summary>、<c>、<example> 和 <code> XML 文档标签的使用。

  // Figure 4

  /// <summary>
  ///     Initializes a new instance of a 
  ///     <c>DocumentationSample</c> type.
  /// </summary>
  /// <example>The following is an example of initializing 
  ///          an <c>DocumentationSample</c> type:
  ///   <code>
  ///       // Create the type.
  ///       DocumentationSample ds = new DocumentationSample;
  /// 
  ///       if ( null == ds )
  ///           return;
  /// 
  ///       return ds.DoSomething( 5 );
  ///   </code>
  /// </example>
  public DocumentationSample() { … }

图 5 展示了 <summary>、<param>、<see>、<exception>、<paramref>、<c> 和 <returns> XML 文档标签的使用。

  // Figure 5

  /// <summary>Causes something happen.</summary>
  /// <param name="someValue">A <see cref="String"/> 
  ///  type representing some value.</param>
  /// <exception cref="ArgumentNullException">
  ///     if <paramref name="someValue"/> is <c>null</c>.
  /// </exception>
  /// <exception cref="ArgumentException">
  ///     if <paramref name="someValue"/> is <c>empty</c>.
  /// </exception>
  /// <returns><paramref name="someValue"/> as passed in.
  /// </returns>
  public string MyMethod( string someValue )
  { 
      if ( null == someValue )
          throw new ArgumentNullException( "Your message." );
  
      if ( 0 >= someValue.Length )
          throw new ArgumentException( "Your message." );
  
      return someValue;
  }

一旦您的源代码文档记录完成，您就需要生成用于生成 Visual Studio .NET 文档报告或 NDoc 帮助文件的 XML 文档文件。

生成 XML 文档文件

Visual Studio .NET 解析 .cs 文件以生成 XML 文档文件；然而，我们需要进行一些配置和步骤才能实现这一点。

我们必须告诉 Visual Studio 生成 XML 文件、文件的名称以及文件的创建位置。为此，在解决方案资源管理器中，右键单击项目并选择属性。这将弹出项目的属性页（参见图 6）。

图 6

在项目的属性页中，在“配置属性”部分下选择“生成”选项。您需要在此页面上关注两个属性。第一个是“输出路径”属性，它告诉编译器将 XML 文档文件写入何处（我通常将路径保留在 bin/Debug 目录，因为这使得使用 NDoc 更加容易）。接下来是“XML 文档文件”属性，它将是您的 XML 文档文件的名称（参见图 7）。单击“应用”，然后单击“确定”关闭项目的属性页。

图 7

生成 XML 文档文件的最后一步是生成项目。一旦您生成了项目，导航到您设置为文档文件“输出路径”的目录，您将看到 .xml 文件（在我这里是 bin/Debug 目录）。

如果您在浏览器或记事本中打开 XML 文件，您将看到 XML 文档编译器已经删除了 XML 文档以生成文件。这也意味着您可以创建自己的 XML 样式表（XSLT）以任意方式格式化文档。

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>DocumentationSample</name>
  </assembly>
  <members>
    <member name="T:Mike.Elliott.Articles.XML.
                   Documentation.DocumentationSample">
      <summary>
        The <c>DocumentationSample</c> 
        type demonstrates code comments.
      </summary>
      <remarks>
        <para>
          The <c>DocumentationSample</c> type 
          provides no real functionality; 
          however, it does provide examples of using the 
          most common, built in 
          <c>C#</c> code comment xml tags.
        </para>
        <para>
          <c>DocumentationSample</c> types are not safe 
          for access by concurrent threads.
        </para>
      </remarks>
    </member>
    <member name="M:Mike.Elliott.Articles.XML.
                  Documentation.DocumentationSample.#ctor">
      <summary>
        Initializes a new instance of a 
        <c>DocumentationSample</c> type.
      </summary>
      <example>The following is an example of initializing an 
      <c>DocumentationSample</c> type:
        <code>
          // Create the type.
          DocumentationSample ds = new DocumentationSample;
          
          if ( null == ds )
            return;
            
          return ds.DoSomething( 5 );
        </code>
      </example>
    </member>
    <member name="M:Mike.Elliott.Articles.XML.
         Documentation.DocumentationSample.MyMethod(System.String)">
      <summary>Causes to happen.</summary>
      <param name="someValue">
        A <see cref="T:System.String"/> type representing some value.
      </param>
      <exception cref="T:System.ArgumentNullException">
        if <paramref name="someValue"/> is <c>null</c>.
      </exception>
      <exception cref="T:System.ArgumentException">
        if <paramref name="someValue"/> is <c>empty</c>.
      </exception>
      <returns><paramref name="someValue"/> as passed in.</returns>
    </member>
  </members>
</doc>

差不多了

现在您已经有了 XML 文档文件，您就可以生成实际的帮助文件或 API 文档了。对于这项任务，我们将使用 NDoc。

NDoc 是一个可扩展的开源代码文档生成工具，适用于 .NET 开发者。您可以从 SourceForge.net 或 NDoc 下载免费的、功能齐全的 NDoc 副本（非常感谢 SourceForge 和贡献了 NDoc 工具的开发者）。

安装 NDoc 后，打开 GUI，以便我们可以构建我们期待已久的帮助文件。

构建帮助文件

NDoc 中有许多配置可以设置，这些配置决定了帮助文件的内容和格式。我在这里只介绍几个，但 NDoc 的贡献作者在文档记录这些选项方面做得非常出色。当您单击一个属性框时，属性的描述会显示在 GUI 的底部（参见图 8）。

图 8

首先，我们需要添加要包含在文档中的 .NET 程序集。请注意，我们有能力包含任意数量的程序集。这使您能够为整个系统或组织创建完全集成的帮助文件系统。如果您的组织要求所有 C# 开发都使用 XML 标签进行完整文档记录，那么您可以将集成帮助文件的生成添加到您的标准构建过程中。

还记得，本文前面我提到我通常将 Visual Studio 项目的“输出路径”保留在 bin\Debug，因为它使得与 NDoc 的工作更加容易吗？在 NDoc 上单击“添加”按钮，导航到程序集文件名，然后选择 .exe 或 .dll 程序集（参见图 9）。

图 9

如果您将“输出路径”保留为 bin\Debug，NDoc 将自动找到 XML 文档文件并填充 XML 文档文件名文本框。如果您更改了“输出路径”，请导航到 XML 文档文件以设置 XML 文档文件名，然后单击“确定”。

在不深入研究 NDoc 属性的情况下，在验证帮助文件内容时，您可以做的有帮助的事情是导航 NDoc 的 UI（用户界面）到“显示缺失文档”部分，并将每个属性设置为 true。这将导致 NDoc 生成的帮助文件以红色标记缺失的文档，以指示文档类型缺失。当您对文档满意后，您可以关闭这些属性（参见图 10）。

图 10

好的，让我们设置几个属性并构建帮助文件。我们想设置的第一个属性是文档类型。我真的很喜欢 MSDN 格式，所以我们将接受它作为默认值。

接下来，在“文档主设置”区域下，我们需要更改 OutputDirectory。我通常在源代码项目文件夹下创建一个 Doc 目录，并将 NDoc 指向该位置（**注意**：NDoc 会生成多个文件）。

最后，在“可见性”部分下，将 DocumentInternals 和 DocumentPrivates 更改为 true。

以上就是基本属性的设置，所以现在我们只需要构建帮助文件并查看它们。要构建文件，请单击工具栏上的构建图标或从“文档”菜单中选择“构建”。一旦 NDoc 完成构建过程，通过单击工具栏上的“查看”图标或从“文档”菜单中选择“查看”来打开帮助文件（参见图 11）。

图 11

记录命名空间

此外，我想讨论如何记录您的类所属的命名空间。

Visual Studio .NET 和 C# 没有提供记录命名空间的方法，因为命名空间只是开发者用来组织和构造代码的逻辑容器。换句话说，您不能使用内联 XML 注释标签来记录命名空间，并期望它们能被正确地解析到您的 .xml 文档文件中。

但是，有一种简单的方法可以通过 NDoc 的 GUI 为命名空间提供摘要级别的描述。如果您注意到图 10（上面两个图像），您将看到 NDoc GUI 上位于“命名空间摘要”按钮。当您单击此按钮时，将出现一个对话框，其中包含一个下拉框，其中包含 NDoc 在您的代码中找到的每个命名空间（参见图 12）。

图 12

以下是为命名空间添加摘要到您的文档的步骤：

单击命名空间摘要按钮以打开命名空间对话框。
从下拉列表中选择要为其提供摘要描述的命名空间（参见图 12）。
添加您希望出现在最终文档中的摘要。
对希望记录的每个命名空间重复步骤 1-3。
保存 NDoc 项目以确保您不会丢失刚添加的命名空间信息。

自定义 XML 注释的格式

最终文档的一个很酷的特点是它们是 HTML 文件。仔细想想，这意味着您可以在 XML 注释中使用传统的 HTML 标签来实现自定义格式。事实上，本文列出的 XML 标签只是映射到 HTML 转换或 CSS 类。例如，当您在 XML 注释中创建项目列表时，NDoc（或 Visual Studio .NET 的 HTML 报告）生成的输出就是典型的 HTML <ul> / <li> 标签对。

  //XML Comments in the source code

  /// <remarks>
  ///   <list type="bullet">
  ///     <item><b>Bold</b>, <i>Italic</i>, <b><i>Bold-Italic</i></b></item>
  ///     <item>Superscript - 1<sup>st</sup></item>
  ///     <item>Subscript - 2<sub>nd</sub></item>
  ///   </list>
  /// </remarks>
  public void HTMLCommentMethod() { ... }

解析、转换和最终注释输出

  <ul type="disc">
    <li><b>Bold</b>, <i>Italic</i>, <b><i>Bold-Italic</i></b></li>
    <li>Superscript - 1<sup>st</sup></li>
    <li>Subscript - 2<sub>nd</sub></li>
  </ul>

我相信您可以看到为您的文档添加粗体、斜体和其他标准 HTML 格式是多么容易，并且您可以看到它的各种用途。由于输出只是 HTML 文件，因此没有什么可以阻止我们使用带有指向外部站点或页面的链接的锚点，添加内联 JavaScript 来打开新窗口，甚至“弹出”警报。以下代码演示了一个带有粗体、斜体、一个 onclick 弹出 JavaScript 警报的锚点（<a>），以及一个 onclick 打开导航到特定 URL 的新窗口的锚点（<a>）。

  /// <summary>
  ///   This method demonstrates comments using <c>HTML</c> tags
  ///   within the <c>XML</c> comments.
  /// </summary>
  /// <remarks>
  ///   <c>HTML tag examples:</c>
  ///   <list type="bullet">
  ///     <item><b>Bold</b>, <i>Italic</i>, <b><i>Bold-Italic</i></b></item>
  ///     <item>Superscript - 1<sup>st</sup></item>
  ///     <item>Subscript - 2<sub>nd</sub></item>
  ///     <item>Javascript Alert - <a href='#' 
  ///        onclick='javascript: alert( "Wow, this is cool!" );'>Alert</a></item>
  ///     <item>New Window -
  ///       <a href="#" onclick='javascript: window.open( 
  ///                                "http://sourceforge.net/projects/ndoc/" );'>
  ///        New Window</a>
  ///     </item>
  ///   </list>
  ///   <hr>
  ///   Something else
  /// </remarks>
  public void HTMLCommentMethod() { ... }

图 13 显示了上述方法的 NDoc 文档。

指向外部站点的锚点的一个有价值的用途是记录在互联网上找到的解决了您项目或代码中某些问题的研究。例如，您可以添加一个指向文档记录了您为已知安全问题实现的修复的站点的链接。

技巧

为了总结本文，我想指出几点，这些点将使 C# XML 文档和 NDoc 的集成真正变得很棒。我特别喜欢生成的帮助文件的一两点是它们采用标准的 .chm 格式，并且它们提供了标准的目录、索引和搜索功能。

另外，请注意，如果您选择 MSDN 作为文档类型，您的帮助文件将与 .NET Framework 的帮助文件集成。在图 11 中，请注意 DocumentationSample 类派生自 System.Object，如果您单击 System.Object 链接，您将被引导到 .NET Framework 的 System.Object 文档（如果您在 Visual Studio .NET 安装期间安装了 MSDN 帮助文件）。

您是否曾经下载过文档质量差或根本没有文档的开源 .NET 程序集？如果程序集是用 C# 编写的，并且开发者使用了 XML 文档标签，那么您可以自己生成 API 文档（我对 Microsoft.Web.UI.WebControls 程序集做了这件事，证明非常有帮助）。

在 Visual Studio .NET 中，一旦您配置了 .NET 项目以生成 XML 文档文件并且构建了项目，您可能会看到一些警告，通知您存在未记录的特性。很多时候，您必须使用 Rebuild 而不是 Build 来正确更新 XML 文件。

一旦我验证了文档，我通常会保存 NDoc 项目，并将 .ndoc 项目文件添加到我的解决方案中，并将其与源代码一起放到版本控制中（**注意**，我只有 .ndoc 项目文件，而不是所有生成的项目文件，因为它们非常容易重新创建）。

摘要

通过使用 C# 内联 XML 文档标签和 NDoc，您可以为您的源代码创建全面的 API 文档。通过将多个程序集添加到同一个 NDoc 项目并与 .NET Framework 帮助文件集成，您可以真正生成一套专业的源代码文档，任何人都会为此感到自豪。

历史

1.0.0.0

最初文章发布

1.1.0.0

添加了关于记录命名空间的部分

1.2.0.0

更新了记录命名空间部分

2.0.0.0

添加了自定义 XML 注释的格式部分