[网摘].NET 程序员十种必备工具-NDoc

NDoc

编 写代码文档资料几乎总是一项令人畏惧的任务。我所说的不是早期设计文档，甚至也不是更为详细的设计文档；我说的是记录类上的各个方法和属性。NDoc 工具能够使用反射来分析程序集，并使用从 C# XML 注释生成的 XML 自动为代码生成文档资料。XML 注释仅适用于 C#，但有一个名为 VBCommenter 的 Visual Studio .NET Power Toy，它能够为 Visual Basic .NET 完成类似的工作。此外，下一版本的 Visual Studio 将为更多语言支持 XML 注释。

使用 NDoc 时，您仍然在编写代码的技术文档，但您是在编写代码的过程中完成了文档编写工作（在 XML 注释中），而这更容易忍受。使用 NDoc 时，第一步是为您的程序集打开 XML 注释生成功能。右键单击该项目并选择 Properties | Configuration Properties | Build，然后在 XML Documentation File 选项中输入用于保存 XML 文件的路径。当该项目生成时，将创建一个 XML 文件，其中包含所有 XML 注释。下面是 NUnit 示例中的一个用 XML 编写了文档的方法：

 
   

  
    
 
      
      
     /**/ 
     /// 
       
     
 
     
 
     /// 
      This test adds a number of values to the Hashtable collection 
 
     /// 
      and then retrieves those values and checks if they match.
 
     /// 
       
     
 
      
     [Test]
 
     public 
       
     void 
      HashtableAddTest()
 
      
     {
     
     // 
     Method Body Here 
     
 
     } 
     
 
    
 
   

有关该方法的 XML 文档资料将被提取并保存在 XML 文件中，如下所示：

< member name ="M:NUnitExample.HashtableTest.HashtableAddTest" >
   < summary > This test adds a number of values to the Hashtable collection
     and then retrieves those values and checks if they match. </ summary >
</ member >

NDoc 使用反射来考察您的程序集，然后读取该文档中的 XML，并且将它们进行匹配。NDoc 使用该数据来创建任意数量的不同文档格式，包括 HTML 帮助文件 (CHM)。在生成 XML 文件以后，下一步是将程序集和 XML 文件加载到 NDoc 中，以便可以对它们进行处理。通过打开 NDoc 并单击 Add 按钮，可以容易地完成该工作。

在将程序集和 XML 文件加载到 NDoc 中并且使用可用的属性范围自定义输出以后，单击 Generate 按钮将启动生成文档资料的过程。使用默认的属性，NDoc 可以生成一些非常吸引人并且实用的 .html 和 .chm 文件，从而以快速有效的方式自动完成原来非常乏味的任务。

NDoc 是一个开放源代码项目，并且可以从 http://ndoc.sourceforge.net/ 下载。