NDoc –NET 代码文档生成器快速度上手

                         感谢：破宝 http://blog.joycode.com/percyboy/ <?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" />

       在线资源：NDoc 1.3 中文版用户指南  

       下载：NDoc中文版安装包下载  NDoc源码下载

NDoc 是一个很好用的.NET小工具，它可以将 C#.NET 编译生成的程序集和对应的 /doc XML 文档，自动转换成如 .NET Framework SDK 类库文档或者 MSDN Library 在线 .NET 类库文档形式的代码文档，让您快速拥有专业级的类库API 文档。(VB.NET 通过第三方插件如 VBCommenter 的支持，也可以生成 XML 文档。)  这里不多说了，现在说说怎么快速使用NDoc生成文档

首先配置我们自己的C#项目，让我们的程序集生成XML文档

<?xml:namespace prefix = v ns = "urn:schemas-microsoft-com:vml" />

注意：XML文档文件名和程序集同名，省去不必要的麻烦；在 NDoc 中，当您加入某程序集时，NDoc 会自动查找这样的“同名” XML 文件。如果找到，就会尝试自动将它当作该程序集的 XML 文档。这样会简化您的操作。

第二步：完善自己的程序的相关注释

比如在一个函数前面输入“///”.NET会自动创建一个 summary XML 文档块:

/// <summary>

///

/// </summary>

/// <param name="s"></param>

/// <param name="s2"></param>

作用也一目了然，生成文档的时候这是很有用的。你的注释越是详细，你生成的文档就会越专业。

这里不得不对比国内和国外的情况了，国内我们的程序员往往花N多时间完成了一个不错的软件或者类库什么的，往往什么文档也没有，别人想学习，想用你的东西，往往被一对烦乱的代码堆砌，吓跑了。那么这个软件或者类库有何意义呢，能给别人带来帮助吗？国外的做法和国内的相差就太大了，他们往往花一半的时间完善他们的注释文档工作，往往10行的小代码段，会有20行的注释，这是很多人无法想象的，但是何为目光短浅，相信聪明人自然明了。

继续说我们的注释，NDoc还支持狠毒其他的标记，需要我们自己输入的，生成文档的时候会看到相应的效果，具体怎么用，往下看。

NDoc支持许多有用的标记，下面有张列表

标记	说明
<event> [NDoc 扩充]	对某个成员可能引发的事件的说明。
<example>	“示例”，帮助类库使用者理解类型/成员使用方法的示例代码。
<exception>	对某个成员可以抛出的异常的说明。
<exclude/> [NDoc 扩充]	指示 NDoc 文档引擎将被标记的类型/成员排除在代码文档之外。 与文档引擎的“可见性”配置不符的，以 exclude 优先。
<include>	将代码文件外部的某 XML 文件中的一部分包含进代码文件来。
<overloads> [NDoc 扩充]	为“重载列表”页面准备摘要、备注、示例等文档内容。只需在重载成员的第一个成员前面书写此区域即可。 <overloads> 标记有两种形式: · 简单的形式，直接在 overload 中写文本，这些文本被处理为“重载列表”页面的摘要。没有备注、示例等区域。 · 复杂的形式，在 overload 内部，包含 summary, remarks, example 等标记分别表示“重载列表”页面的摘要、备注、示例等。 示例: ///<overloads>This method has two overloads.</overloads> ///<summary>This overload just says hello.</summary> public void SayHello() { ... } ///<summary>This one says hello to someone.</summary> public void SayHello(string toSomeone) { ... }
<param>	成员的参数说明。
<permission>	访问某成员所必需的 .NET Framework 安全性 CodeAccessPermission。
<preliminary> [NDoc 扩充]	将某类型/成员标记为“预发布”。内部的文本被当作警告文本用红色显示，可以包含 <para> 表示多行文本。如果缺少内部文本，则显示默认的警告文本: “[此文档为预发布版本，在未来版本中有可能改变。]”。 如果需要把全部类型/成员都标记为“预发布”，请使用文档引擎的 Preliminary 配置项。
<remarks>	“备注”，对 <summary> 的进一步注解。
<returns>	“返回值”。
<seealso>	向页面的“请参见”区域添加一个链接。 请不要将此标记包含在 <remarks> 内部，它是一个顶级标记。 两种可选的语法: · <seealso href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</seealso> · <seealso cref="System.Data.DataSet">DataSet</seealso>
<summary>	“摘要”，对类型/成员的摘要说明。
<threadsafety> [NDoc 扩充]	“线程安全”，说明类型在多线程环境中是否安全。 NDoc 提供 static 和 instance 两个布尔的属性，可以自动生成像 .NET Framework SDK 类库文档中那样的标准文本。 threadsafety 标记内部可以包含额外的文本，会被显示到标准文本的下方，说明额外的信息。例如: /// <summary>The summary description for SafeClass.</summary> /// <threadsafety static="true" instance="true"> ///    <para>More information about using this class across thread</para> /// </threadsafety> public class SafeClass() { ... }
<value>	“属性值”。

Block 标记

Block 标记用于 Section 标记的内部，它们将显示在单独的行中。

标记	说明
<code>	多行的代码块。
<list>	一个列表或表格。
<note> [NDoc 扩充]	“注意”块。 例如: /// <summary> /// <note>This is a note in the summary.</note> /// </summary> public class SomeClass() { ... } 将生成: 注意 This is a note in the summary.
<para>	表示一个段落。

Inline 标记

Inline 标记可以用于其他 Section 标记或 Block 标记内部，它们将和前后的文本显示在同一行中。

标记	说明
<c>	将内部文本格式化为代码样式，用于表示行文中提到的短小代码片段。
<paramref>	加入指向方法参数的链接。
<see>	加入指向某个类型/成员或网络 URL 的链接。 两种可选的语法: · <see href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</see> · <see cref="System.Data.DataSet">DataSet</see> · <see langword="xxx"/> 其中 xxx 可以是 null, sealed, static, abstract 或 virtual。

 

第三步：就是使用我们的NDoc工具了

如果您使用 Visual Studio.NET 开发工具，那么最简单的方法就是点击工具条中的“从 Visual Studio .NET 解决方案新建 NDoc 项目...”按钮。

 

然后，NDoc 会要求您选择某种编译配置(如 Debug 或 Release，或者其他您自定义的编译配置)，这取决于您将使用哪种编译配置下生成的程序集和 XML 文档。

编译配置选择对话框

“确定”之后，NDoc 项目设计器将自动生成一个新的 NDoc 项目，其中已包含解决方案中各个项目生成的程序集和相应的 XML 文档。

如果您没有使用 Visual Studio .NET，则需要手工向 NDoc 项目添加要生成代码文档的程序集和相应的 XML 文档。您可以通过点击设计器重的“添加”按钮、从文件系统中浏览并选择要添加的程序集，也可以直接从 Windows 资源管理器或“我的电脑”中、直接拖动要生成代码文档的程序集、到设计器中的程序集列表框中。

请确保您打开了 /doc 文档输出的选项，否则 NDoc 输出的代码文档只能有很少的内容。选择文档引擎

NDoc 内置了若干文档引擎，它们可以用于生成不同风格、样式、格式的代码文档。每种文档引擎都定义了它自己的排版、格式，以及要输出的内容。

最受欢迎的两种文档引擎是 MSDN 和 VS.NET 2003。它们都生成类似 .NET Framework SDK 类库文档样式的代码文档，不同的是前者最终编译成 HTML Help 1 （即 *.CHM）格式的整合文件，后者最终编译成 Microsoft Help 2 (即以形如 ms-help://... 的 URI 地址访问的文档)格式的形式。

NDoc 1.3 中，新增了 MSDN 2003 文档引擎，在保留 MSDN 文档引擎的特点之外，向接近 .NET Framework SDK 类库文档的方向又前进了一大步：加入了语言选择器等特色功能。

NDoc 文档引擎

所有的文档引擎都共享一些配置项，比如要输出哪些类型/不输出哪些类型等；每种文档引擎都会有一些额外的配置项，用于特定的配置。

这里还有要说的就是这些文档引擎，需要安装相应的支持工具

HTML Help 1 编译器

HTML Help 1 文件，也就是 CHM 文件，是很常见的应用程序帮助文件格式，在 Visual Studio .NET 发布之前，MSDN 一直采用的就是 HTML Help 1 格式。

如果您准备创建 HTML Help 1 (*.CHM)文件，请确认您已经安装好 Microsoft's HTML Help Workshop。此下载安装包已包含必需的 HTML Help 1 编译器。

Microsoft Help 2 编译器

Microsoft Help 2 是 Microsoft 从 Visual Studio .NET 2002 开始使用的、一种新的帮助文档格式。

如果您准备创建 Microsoft Help 2 (*.HxS)文件，请下载并安装 Visual Studio Help Integration Kit (VSHIK)。此工具包已包含所必需的 Microsoft Help 2 编译器。

Latex 编译器

如果您准备使用 LaTeX 文档引擎创建 dvi 或 pdf 文件，您需要下载并安装一个 LaTeX 系统，比如免费的 MikTeX。

生成代码文档

选择好文档引擎，并做好相应的配置。您就可以点击“生成”按钮让 NDoc 创建您需要的代码文档了。设计器下方的“输出”窗口中将显示文档制作中的消息，状态条上的进度条指示生成的整体进度。

 

NDoc 生成进度

查看文档 生成成功后，您可以点击“查看文档”按钮查看生成的代码文档。

最后，希望大家用好这个小工具，让我们的程序代码更有价值。