ndoc使用,NDoc 用户指南(一)

• 欢迎使用 NDoc
  • What's New?
  • 已知问题
• 快速教程
  • 配置您的 C# 项目
  • “装饰”您的代码
    • NDoc 支持的标记
    • NDoc 支持的属性 (Attribute)
  • 新建 NDoc 项目
• NDoc 设计器
  • 选项
• NDoc 命令行工具
  • 使用 NDoc 命令行自动生成代码文档
• NDoc 文档引擎
  • VS.NET 文档引擎
    • 指向其他文档集合的 XLinks
    • 与 Visual Studio .NET IDE 的集成
    • Microsoft Help 2 部署
  • MSDN 文档引擎
  • MSDN 2003 文档引擎
  • XML 文档引擎
  • JavaDoc 文档引擎
  • Linear HTML 文档引擎
  • LaTeX 文档引擎
• NDoc 支持的标记
  • 标记用法
  • <c>
  • <code>
  • <event>
  • <example>
  • <exception>
  • <exclude>
  • <include>
  • <list>
  • <note>
  • <overloads>
  • <para>
  • <param>
  • <paramref>
  • <permission>
  • <preliminary>
  • <remarks>
  • <returns>
  • <see>
  • <seealso>
  • <summary>
  • <threadsafety>
  • <value>
• 定义您自己的标记
  • 可用 Section 的列表
• NDoc 开发者参考
• 加入 NDoc 开发
• 支持资源

关于 NDoc
NDoc 可以将 C#.NET 编译生成的程序集和对应的 /doc XML 文档，自动转换成如 .NET Framework SDK 类库文档或者 MSDN Library 在线 .NET 类库文档形式的代码文档，让您快速拥有专业级的类库API 文档。(VB.NET 通过第三方插件如 VBCommenter 的支持，也可以生成 XML 文档。)
NDoc 代码文档的样式包括 HTML Help 1 (即 *.CHM 格式)，Microsoft Help 2 (即以形如 ms-help://... 的 URI 地址访问的文档)，以及 MSDN 在线网页样式的 .NET Framework 类库文档。
NDoc 为开放源代码项目，采用 GNU General Public Licence 授权协议（除非您的软件/项目也采用 GPL 协议开放源代码，否则您不能在您的软件/项目中使用 NDoc 源代码中的任何部分）。更多的授权问题，请参见 GNU FAQ。
感谢您使用我们的软件，也期待着您的参与（建议、BUG 反馈、代码贡献）！
使用 NDoc 之前
请阅读 GNU General Public Licence 和 GNU FAQ。
请阅读 已知问题。
请阅读 必要的帮助文件编译器。
NDoc 各本地化版本
英文版: NDoc in English
简体中文版: NDoc in Simplified Chinese
德文版: NDoc in German
日文版: NDoc in Japanese
(此列表可能并不完整。欢迎大家给我发送更多关于 NDoc 的本地化版本的网址！)
关于中文版
此 NDoc 1.3 (中文版) 由 破宝(percyboy) 翻译，遵循 GPL 协议的要求发布源代码。有关中文版的翻译问题和 bug 等，都可以通过我的博客和我联系。
NDoc 1.3 - What's new?
NDoc 1.3 包含了大量更新和改进，也修复了许多 bug。
亮点
NDoc 1.3 包含了许多新功能:

• 完全重写了 Microsoft Help 2 文档引擎，即 "VS.NET 2003 文档引擎"。
• 支持更多新的注释标记，如 preliminary, threadsafety 和 exclude。
• 支持 ObsoleteAttribute 和 FlagsAttribute 属性。
• NDoc 1.3 改进了可扩展性，允许您定义自己的注释标记，并控制它们的显示样式。
• 用户界面更加友好。
• 程序集的解析及文档制作过程，在性能上有了大的提高。
• 与 MSDN 各帮助主题更好的共存。

VS.NET 2003 文档引擎
新的 VS.NET 2003 文档引擎用于制作 Microsoft Help 2 形式的文档，完全按照 Microsoft 的说明，在每页头部都加入了特定的 XML 数据岛，从而和 Visual Studio .NET 2003 合并文档集合更好的兼容，和 Visual Studio .NET IDE 更好的集成(比如更好的支持“动态帮助”功能等)。
新的文档引擎可以制作出和最新 Microsoft 文档格式更为接近的文档，比如新增的语言筛选器等功能。
更多的细节请参看 VS.NET 2003 文档引擎。
性能
所有文档引擎的性能都有很大程度的提高。

• NDoc 中间 XML 数据文件的制作过程有了相当的提速，现在这个过程在整个文档生成过程中所占的时间比例已经很小了。
• 页面制作的时间也减少了 20% ~ 50%。
• 内存占用显著降低了。
• 命名空间层次结构页面的制作过程，得到了改进，不再担心性能或稳定性问题了。因此，文档引擎总是制作命名空间层次结构页。

程序集加载
程序集的加载方法有了不少改进。

• 程序集改变时，GUI 程序不需要重新启动就能反映更新。
• 大多数程序集可以从网络共享地址加载。但是，因为 .NET Framework 的安全限制，由托管 C++ 生成的程序集必须在本地磁盘中，不能从网络共享地址中正常加载。
• 程序集的解析得到了改进，现在已经极少出错了。

国际化
NDoc 现在可以正常处理程序集及代码注释中包含的非英文字符。除 MSDN 文档引擎(HTML Help 1 格式)之外，其他文档引擎都完全支持 Unicode (UTF-8)字符。受 HTML Help 1 的局限，MSDN 文档引擎不支持混合字符集，这是我们所无法控制的。
注意，尽管 NDoc 支持多种字符集，但 NDoc 生成的代码文档的各个标题、及 NDoc 的界面、提示消息等文本，在 NDoc 1.3 中还未实现多语言显示。
NDoc 并行运行能力
多个 NDoc 实例现在可以同时并行运行。先前的文件锁定等问题已经得到解决。
用户界面

• 对拖放操作的支持。新版本中，您可以直接将程序集从资源管理器中拖曳到 NDoc GUI 的程序集列表中。
• 错误处理。新版本的错误处理得到了显著的改进。
• 帮助编译器消息。帮助编译器的消息被记入 log。如果出错，错误消息被显示出来。
• 属性网格。属性网格有了不少加强。
• 能处理程序集加载错误。
• 对没有 XML 文档的程序集，也能为输出简单的代码文档。
• 对相对路径的支持。一般都是相对于 NDoc 项目文件。

XML 文档标记
新标记
标记
说明
<exclude/>
Directs NDoc to exclude the tagged type or member from the documentation.
The tag overrides all visibility options.
<preliminary>
Marks the documentation of a type or member as preliminary.
This tag can include text and block tags like <para> in order to put a custom warning into your help topics about preliminary items.
If the tag is empty, preliminary topics will include the default message:
[This is preliminary documentation and subject to change.]
It is also possible to mark an entire help project as preliminary using the Preliminary project setting.
<devdoc>
增强的标记
标记
说明
<code>

• "lang" attribute
• No more <include> to prevent indent
• "Escaped" attribute

<see>
langword
配置
新配置项
NDoc 1.3 加入了下面的通用配置项:
配置项
说明
文档主要配置
CleanIntermediates
是否在文档成功生成后，删除中间文件。
比如 MSDN 和 VS.NET 文档引擎会编译为单一文件，它们的中间文件包括所有编译前的网页、HTML Help 项目文件等。
FeedbackEmailAddress
用户反馈接收 Email 地址。将在输出的代码文档每页的底部添加放置指向此 Email 地址的超链接。
Preliminary
若此项为真，文档引擎将在每个页面中添加红色的消息“[此文档为预发布版本，在未来版本中有可能改变。]”。
SdkDocVersion
指示文档引擎应将 .NET Framework 标准类库中包含的类型的超链接指向哪个版本的 .NET Framework SDK。
SdkDocLanguage
指示文档引擎应将 .NET Framework 标准类库中包含的类型的超链接指向哪种本地化语言版本的 .NET Framework SDK。
属性(attribute)的输出
DocumentInheritedAttributes
是否输出从基类中继承而来的属性(attribute)。如果 DocumentAttributes = false，则此配置被忽略。
输出过滤
DocumentedInheritedMembers
如何输出继承的成员：可选择不输出、只输出继承的实例成员或者是全部继承成员都输出。
它有三个选项:
None
不输出继承的成员。
Instance
只输出继承的实例成员。(默认选项)
InstanceAndStatic
输出全部继承的实例和静态成员。
DocumentInheritedFrameworkMembers
是否输出从 .NET Framework 中的类、结构等继承下来的成员。(默认为输出)
注意: 如果 DocumentInheritedMembers 为 None, 此配置被忽略。
DocumentExplicitInterfaceImplementations
是否输出显式实现的接口成员。(默认为否)
DocumentSealedProtected
是否输出密封类 (sealed, VB.NET 中为 NotInheritable) 的 protected 成员。(默认为否)
注意: 如果 DocumentProtected 为 false，则忽略此项配置。
SkipNamespacesWithoutSummaries
是否跳过缺少概述信息的命名空间。(默认为否)
删除的配置项
NDoc 1.3 删除了下面的配置项:
配置项
说明
GetExternalSumeries
NDoc 中间 XML 数据文件制作的性能有了相当的改进。因此，总是尝试为从 .NET Framework 继承而来的成员查找摘要信息。
IncludeNamespaceHierarchy
命名空间层次结构页面的制作过程，得到了改进，不再担心性能或稳定性问题了。因此，文档引擎总是制作命名空间层次结构页。
MSDN 文档引擎
新配置项
NDoc 1.3 为 MSDN 文档引擎加入了下面的配置项:
配置项
说明
文档主要配置
BinaryToc
是否以二进制方式创建目录树文件。这将显著提高大尺寸 CHM 文件的打开速度。
默认此项被设置为 true。但启用此配置项，有一些强制的限制必须满足。如果您遇到问题，可以尝试关闭此功能。更多细节请查看 HTML Help Workshop 的文档。
Title
此文本将显示在每个页面的左上角，一般填写类库的名称比较合适。
扩展性
ExtensibilityStylesheet
用户自定义的 NDoc 扩展 XSLT 转换文件，用于转换用户自定义的特殊标记。请参见 NDoc 可扩展性。
HTML Help 选项
AdditionalContentResourceDirectory
页面中涉及到的资源文件（如图片等）所在的目录。此目录及其子目录中的所有文件，将以原有的目录结构包含进 HTML Help 项目中，使用相对路径的超链接不需要做大的调整。
注意: 此文件夹中第一层次的文件，和 NDoc 生成的 HTML 文件、以及通过 FilesToInclude 包含进来的文件，将处在同一层次上，请依次类推其他文件的相对 URL。
LangID
HTML Help 文件的 LangID 设置。中文版默认为 2052。
删除的配置项
NDoc 1.3 删除了下面的配置项:
配置项
说明
SortTOCByNamespace
在 NDoc 1.3 中，各命名空间对应的目录结点总是按字母排序。
SplitTOCs
在老的 MSDN 文档引擎中，此配置项用于克服一些限制。新版本中绕开了它。
DefaultTOC
CHM 目录中第一个命名空间结点总是被默认被选中。
LinkToSdkDocVersion
此配置项现在区分为 SdkDocVersion 和 SdkDocLanguage，且提升为所有文档引擎的通用配置项。
NDoc 1.3 仍然会尝试解析此配置，如果您重新保存，NDoc GUI 会用新的配置项改写。
改进的超链接逻辑
<see> 将形成一个指向另一个类型/成员的文档的链接。在 NDoc 1.3 中，如果一个 HTML 页中出现了多个指向同一个类型/成员的文档的 <see>，则只转换第一个为超链接，其余的不表示为超链接、只显示为粗体。这将使页面不至于太杂乱。
HTML Help 1 目录树中的图标
目录树中，不再出现问号(?)图标。如果没有指定，显示为空白页图标。
运算符和类型转换
NDoc 1.3 修复了对运算符和类型转换的处理 bug，页面格式也更接近 .NET Framework SDK 类库文档。
特别的属性
ObsoleteAttribute
MSDN, MSDN 2003, VS.NET 2003 文档引擎，将自动为具有 ObsoleteAttribute 属性的类型/成员添加红色的提示文本。

• 在命名空间列表及类型的成员列表中，将为它们显示红色的“已过时。”
• 在类型概述页/成员页中，将为它们添加红色的“注意：此成员现已过时。”

FlagsAttribute
如果枚举具有 FlagsAttribute 属性，MSDN, MSDN 2003, VS.NET 2003 文档引擎将自动为它们添加如下的文本:
“此枚举具有允许按位组合其成员值的 FlagsAttribute 属性。”
NDoc 1.3 的已知问题和限制
事项
说明
特别长的类型名称
NDoc 为每一个主题自动在硬盘上创建一个 HTML 文件。目前，文件名是根据完全限定名生成的。如果某类型/成员的完全限定名 (命名空间 + 类型 + 成员名) 的总字符数超过 _MAX_FNAME (256 字符)，NDoc 将无法创建这样的文件，因为操作系统不支持如此多字符的文件名。另外，文件所在完整路径的字符也不能超过 _MAX_PATH (260 字符)。
如果完全限定名的字符数在 200 字符左右，那么您可能需要将 OutputDirectory 配置为一个靠近根目录的位置，这样可以避免文件的完整路径超出 260 字符。
但还没有关于文件名超出 256 字符的解决方法。
在未来某版本的 NDoc 中，我们会尝试解决此问题。
大小写敏感问题
文件名不是大小写敏感的，因此当 MSDN 文档引擎或者 JavaDoc 文档引擎创建 HTML 文件时，如果某些类型或成员只是在大小写上不一样，就会出现问题。
请尝试避免出现这种情况。（例如：公共属性为 Thing，私有字段为 _thing, 避免出现Thing 和 thing 并行。当然，如果不输出私有字段，并行也没有问题。只是说准备输出的类型/成员不要出现这种情况。）
在未来某版本的 NDoc 中，我们会尝试解决此问题。
StrongNameIdentityPermissionAttribute
标记有 StrongNameIdentityPermissionAttribute 属性的程序集，需要有特殊的密钥才能被读取。NDoc 尝试为这样的程序集生成代码文档时，会抛出异常。
您可以考虑使用“条件编译”(#if...)方式为 NDoc 准备没有添加该属性的编译版本。
Compact Framework 不兼容
为 .NET Compact Framework 编译的程序集，当添加到 NDoc 项目中时，NDoc GUI 程序可能抛出异常。尤其是当该程序集引用了 Microsoft.WindowsCE.Forms 或 SqlServerCe 时，更是如此。
还没有找到此问题的解决方法。
在未来某版本的 NDoc 中，我们会尝试解决此问题。
本地化
NDoc 当前不支持本地化的文档格式及 GUI 文本
在未来某版本的 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。
其他工具
H2Reg
向客户机部署 Microsoft Help 2 帮助文档，不像 HTML Help 1 那样简单(仅复制即可完成)。VSHIK 工具包介绍了 如何向客户机部署 Microsoft Help 2 帮助文档的详细步骤和指导。
另外一种方案是采用共享软件 H2Reg utility (开发商: helpware.net)。
H2Reg 许可您将它包含进部署安装包中，它可以用来注册 Microsoft Help 2 命名空间和帮助标题等。H2Reg 使用 INI 文件描述要部署的帮助文档结构。NDoc 创建符合 H2Reg 需要的 INI 文件，指示它进行命名空间的注册工作。
首先，您应该确认，您已经打开了 C# 项目的 /doc 开关，当 Visual Studio .NET 编译时，每次都会生成相应的 XML 文档。
如果没有特殊情况，请让项目输出的程序集名称和 XML 文档文件名、仅仅扩展名不同(比如程序集是 NDoc.Test.dll/NDoc.Test.exe，XML 文档是 NDoc.Test.xml)。在 NDoc 中，当您加入某程序集时，NDoc 会自动查找这样的“同名” XML 文件。如果找到，就会尝试自动将它当作该程序集的 XML 文档。这样会简化您的操作。
打开项目的“属性”对话框，

找到程序集名称
设置 XML 文档文件为程序集名称(扩展名改为 xml)。别忘了设置此项之前，选择“所有配置”，让 Debug 或 Release 配置下，都自动生成 XML 文档。

设置 XML 文档文件配置
现在，每次使用 VS.NET 编译您的程序集，都会自动从源代码中提取所有的 XML 注释，生成 XML 文档文件。
如果您使用的不是 Visual Studio .NET，您同样应该尝试打开 C# 编译器的 /doc 选项。
The more, the better
您在代码中书写的 XML 注释越多，最终生成的代码文档越专业。程序集的使用者越能从中获得帮助。
一般而言的最低要求，对于每一个公共类型，应该给它的所有公共的和受保护的成员添加 <summary> 注释，以描述该成员表示什么意义或者会做些什么动作。
在 VS.NET 中，C# 代码编辑器，提供了一些自动完成的功能，帮助我们创建基本的 XML 注释。
比如如下的代码:
public class MyClass() {
public MyClass( string s ) { }
}
把光标移动到 MyClass 构造函数的上面一空行，敲 '/' 键三次，VS.NET 自动创建一个 summary XML 文档块:
public class MyClass() {
/// <summary>
///
/// </summary>
/// <param name="s"></param>
public MyClass( string s ) { }
}
这种操作对于所有可以书写 XML 注释文档的成员都有效。另外，在以 '///' 开头的 XML 注释行中，敲入 '<' 字符，VS.NET 自动感知功能将自动显示可用的 XML 注释标记列表。不过，这个列表不包括 NDoc 所支持的额外的标记，这些额外的标记，您需要手工敲入。
NDoc 可以配置为输出所有的成员，包括私有的和内部的成员，虽然这些成员无法在程序集外部被调用，但如果您需要，您可以同样为这些成员添加 XML 注释，NDoc 会帮您生成这样的适合内部使用的代码文档。
NDoc 内置的 MSDN, MSDN 2003, VS.NET 文档引擎，支持 C# 程序员参考中的所有 XML 文档注释标记。
NDoc 支持扩充的标记和语法。某些标记只能用于特定的类型（类，结构，委托，接口，枚举）或成员（字段，属性，方法，事件等），请参见标记用法。
NDoc 将标记区分为三类: Section 标记，Block 标记，Inline 标记。
Section 标记
Section 标记用于定义不同的代码文档的区域。它们都是顶级标记，Block 标记、Inline 标记都应包含在某个 Section 标记的内部。（除非自定义了扩展 XSLT 转换，否则，在 Section 标记外部的 Block 标记或 Inline 标记都被忽略。）
标记
说明
<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 _disibledevent=>

<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 中的 MSDN 文档引擎和 VS.NET 文档引擎使用了一些 属性 来控制代码文档中一些特殊样式。
如果类型或成员具有以下属性，NDoc 将显示相应的特殊样式，使文档看起来更加专业。
属性
说明
ObsoleteAttribute
标记该类型或成员为“已过时。”
FlagsAttribute
指示可以将枚举作为位域（即一组标志）处理，允许按位组合其成员值。
NDoc 将仿照 .NET Framework SDK 文档中处理方式：

• 在该枚举摘要下面显示“此枚举具有允许按位组合其成员值的 FlagsAttribute 属性。”
• 在枚举成员的列表中添加“值”列，显示每个枚举成员对应的枚举值。

EditorBrowsableAttribute
使用此属性(attribute)的成员将不显示在 VS.NET 的属性窗口、对象浏览器及智能感知等列表中，根据 NDoc 项目配置中的 EditorBrowsableFilter 配置，NDoc 可以将这部分被隐藏的成员排除在代码文档之外。
注：在 NDoc 1.3 中，我们推荐您使用 <exclude/> XML 文档标记在代码文档中隐藏某些类型或成员。
AssemblyVersionAttribute
根据 NDoc 项目配置中的 AssemblyVersionInfo 配置，NDoc 可以在代码文档中包含通过 AssemblyVersionAttribute 属性指定的程序集版本信息。
新建 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 文档引擎
所有的文档引擎都共享一些配置项，比如要输出哪些类型/不输出哪些类型等；每种文档引擎都会有一些额外的配置项，用于特定的配置。
更多的细节请参看文档引擎。
生成代码文档
选择好文档引擎，并做好相应的配置。您就可以点击“生成”按钮让 NDoc 创建您需要的代码文档了。设计器下方的“输出”窗口中将显示文档制作中的消息，状态条上的进度条指示生成的整体进度。

NDoc 生成进度
查看文档
生成成功后，您可以点击“查看文档”按钮查看生成的代码文档。
概述
NDoc 项目文件保存了您要输出代码文档的程序集、相应的 XML 文档、选用的文档引擎及配置参数等信息。

NDoc 项目设计器
新建 NDoc 项目的工作可以很简单：选择要输出代码文档的程序集、相应的 XML 文档、选择一个文档引擎并做好配置参数。
命名空间摘要
标准的 C# 注释 XML 文档中，没有提供任何标记为命名空间提供“summary”文档。NDoc 提供了两种途径允许您为命名空间提供“summary”文档。一种是通过在您的代码加入特定的类，并对 NDoc 文档引擎作相应配置（请参见 NDoc 文档引擎 中关于 UseNamespaceDocSummaries 配置项的说明）。另一种途径是通过项目设计器指定各命名空间的摘要文档。
在项目设计器中，单击“命名空间摘要”按钮，在弹出的“编辑命名空间摘要”对话框中，给每个命名空间填写摘要文档。
这些摘要文档将包含在最终生成的代码文档中。

编辑命名空间摘要对话框
文档引擎配置
各种文档引擎间共享一些基本配置项，比如输出过滤(是否输出 private 成员等)，缺少文档时的处理对策等；各文档引擎又包含自己的某些特殊配置项。这些配置项都可以通过项目设计器查看、更改，并保存到项目文件中。
设计器中配置项以类别排列，并且，选中某一配置项时会显示一小段提示文本，说明该配置项的用途和用法。这些都将帮助您快速掌握这些文档引擎的使用方法。
关于完整的文档引擎列表，及其配置项，请参见 NDoc 文档引擎。
选项
选项
说明
ShowProgressOnBuild
如果为真，在文档生成动作启动时，消息输出窗口将自动显示出来。
LoadLastProjectOnStartup
如果为真，每次启动 NDoc 时将自动加载最后一次打开的项目文件。此配置和登陆的 Windows 用户相关。
MRUSize
“最近的项目”列表中显示的最大条目数。
HtmlHelpWorkshopLocation
HTML Help Workshop 软件安装路径，即 HHC.exe 编译器的所在目录。仅对 MSDN 和 MSDN 2003 文档引擎有效。
默认情况下，MSDN 和 MSDN 2003 文档引擎会尝试查找 HTML Help 1 编译器的所在位置，但仍会出现无法定位的情况。这时，NDoc 会提示您无法找到 HHC.exe 编译器，您需要设置此配置项解决问题。
此配置为机器级别的配置，在此机器上的任何 Windows 用户都共享此配置。
概述
NDoc 不仅提供了 GUI 的界面，也同时提供了命令行工具(NDocConsole.exe)，为和其他开发工具集成提供了方便。

语法
NDoc 命令行使用简单的“name-value 对”语法来指定相应的配置项。每个选项前用一个短线，如：-name=value，短线和等号周围不要有空格。下面语法叙述中，中括号的部分是可选的。路径中如果包含有空格，则需要用引号(")括起来。

延伸阅读