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 one says hello to someone.</summary> public void SayHello(string toSomeone) { ... }
<param>	成员的参数说明。
<param>	访问某成员所必需的 .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 中的 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，短线和等号周围不要有空格。下面语法叙述中，中括号的部分是可选的。路径中如果包含有空格，则需要用引号(")括起来。
　用法 1

NDocConsole 程序集[,XML文档] [程序集[,XML文档]]...
[[-referencepath=文件夹] [-referencepath=文件夹]...]
[-namespacesummaries=文件名]
[-documenter=文档引擎]
[[-引擎参数=值] [-引擎参数=值]...]
[-verbose]

 

注释:

• 程序集: 要生成文档的完整路径。
• XML文档: 对应的 XML 文档（C# 编译器 /doc 输出的 XML 文档）。
  缺省时，将自动查找和程序集相同路径、相同名称，仅扩展名不同(.xml)的 XML 文件代替。
• referencepath: 引用的第三方 dll 的搜索路径。
• namespacesummaries: 要使用的 命名空间摘要 XML 文档 的完整路径。
• documenter: 要使用的文档引擎的名称。注意此项区分大小写。
  缺省时，将使用 MSDN 文档引擎。
• 引擎参数: 文档引擎的配置参数名称，注意此项区分大小写。
• 值: 给引擎参数设置的值。
• verbose: 显示文档生成进度的输出消息。

用法 2

NDocConsole -recurse=文件夹[,最大读取深度]
[[-referencepath=文件夹] [-referencepath=文件夹]...]
[-namespacesummaries=文件名]
[-documenter=文档引擎]
[[-引擎参数=值] [-引擎参数=值]...]
[-verbose]

注释:

• recurse: 您可以将要生成文档的程序集和它们对应的 XML 文档放在同一文件夹中（注意：XML 文档的文件名应和对应的程序集文件名相同，仅扩展名不同），将此文件夹指定给此参数，NDoc 将自动查找程序集和 XML 文档。这是一种比较简单的用法。
• 最大读取深度: 在 recurse 参数指定的文件夹中的读取深度。
• referencepath: 引用的第三方 dll 的搜索路径。
• namespacesummaries要使用的 命名空间摘要 XML 文档 的完整路径。
• documenter: 要使用的文档引擎的名称。注意此项区分大小写。
  缺省时，将使用 MSDN 文档引擎。
• 引擎参数: 文档引擎的配置参数名称，注意此项区分大小写。
• 值: 给引擎参数设置的值。
• verbose: 显示文档生成进度的输出消息。

用法 3
　NDocConsole [-documenter=文档引擎] -project=NDOC项目文件 [-verbose]
　
　注释:

• documenter: 要使用的文档引擎的名称。注意此项区分大小写。
  缺省时，将使用 MSDN 文档引擎。
• project: 您可以使用 NDoc GUI 界面保存一个 NDoc 项目文件，然后设置给此参数。
• verbose: 显示文档生成进度的输出消息。

用法 4
　NDocConsole [-help] [文档引擎 [引擎参数]]
　
　where:

• help: 显示命令行帮助信息。
  如果文档引擎参数没有指定，显示 NDoc 命令行的基本语法。
• 文档引擎: 显示此文档引擎的帮助信息（如：可用的配置参数项等）。注意此项区分大小写。
  如果引擎参数没有指定，显示此文档引擎可用的配置参数列表。
• 引擎参数: 显示文档引擎的某配置参数的信息，如描述、默认值。若参数为枚举类型，还会列出可用的枚举值（使用时注意区分大小写）。

可用的文档引擎
　NDoc 1.3 自带的文档引擎包括: JavaDoc, LaTeX, LinearHtml, MSDN, MSDN_2003, VS.NET_2003, 以及 XML。

您可以使用 NDocConsole -help 看到实际的列表。

命名空间摘要 XML 文档的语法

<namespaces>
<namespace name="My.NameSpace">My summary.</namespace>
<namespace name="My.OtherNameSpace">My other summary.</namespace>
...
</namespaces>

配置 NAnt(暂无)

配置 VS.NET
　您可以利用 VS.NET 中提供的生成事件功能，将 NDoc 配置为在每次代码编译完成后、自动生成相应的代码文档。同时 NDoc 代码文档生成将花费不少时间，因此建议您只在 Release 配置状态(或其他自定义的配置状态)时允许自动文档生成。

而 C# 项目的生成事件并不区分各种配置状态(如 Debug 或 Release )，因此需要在生成事件的脚本中添加对配置状态(VS.NET 内置的编译变量)的判断，如：

if $(ConfigurationName) == Release
　因为直接在生成事件窗口中正确书写 NDoc 命令行命令及相关参数、很困难也很容易出现错误，因此您可以将命令写在一个批处理 .bat 文件中，而在项目的生成后事件中引用这个批处理文件(如下图)，这样比较容易书写和维护。

Calling a batch file from the post-build event

一个解决方案中有多个项目时，如果您要得到一份整合的代码文档，您可以只在编译顺序中最后的那个项目配置中，填写这个生成后事件命令。如果您想为每个项目单独生成一份文档，则需要分别去配置。您可以根据您的实际情况决定。

关于 NDoc.bat 中的写法，您可以参考下面的命名行（它对应于上面图中的生成后事件命令）：

IF NOT %1 == Release GOTO end

"%ProgramFiles%\NDoc 1.3\bin\net\1.1\NDocConsole.exe" -recurse="%2bin\%1"

:end
　复杂的解决方案中，可能需要更加复杂的配置，比如有时配置第三方 dll 的搜索路径等，仔细研究一下 NDocConsole.exe -help 的帮助信息吧！

其他开发工具的配置
　大多数开发工具都有运行命令行程序的选项，这些开发工具都可以使用 NDoc 命令行来实现代码文档的自动生成。每种开发工具的配置方法可能不同，但思路都很类似上面关于 VS.NET 中的想法。

概述
　文档引擎是生成各种格式代码文档的组件。NDoc 1.3 内建了以下文档引擎:

• VS.NET
• MSDN
• MSDN 2003
• XML
• JavaDoc
• LinearHtml
• LaTeX
  NDoc 的设计具有很强的可扩展性，您可以自己创作输出特定格式文档的、新的文档引擎。

代码文档的制作一般分作两大环节:

1. 将从程序集中通过反射发出读取的类型/成员信息，和 /doc XML 文档中的注释文档，合并在一起，即 NDoc 中间 XML 数据文件。
2. 通过 XSLT 转换将 NDoc 中间 XML 数据文件转换为目标 HTML 格式。
   您可以通过 XML 文档引擎得到 NDoc 中间 XML 数据文件，经过分析和转换，创作您自己的文档引擎。

下面配置项，是 NDoc 所有文档引擎中通用的配置项，各文档引擎还可以有自己的一些特殊配置，详见文档引擎的文档。

通用的配置

配置项

说明

(全局)

ReferencePaths

一组额外的程序集搜索路径。
注意：这是一个 NDoc 项目级别的属性，各文档引擎共享此项配置。

文档主要配置

AssemblyVersionInfo

如何输出版本信息。
可选项为:

None	不输出版本信息。(默认选项)
AssemblyVersion	输出标准 .NET 的版本号，即通过 AssemblyVersionAttribute 属性设置的版本号。
AssemblyFileVersion	通过 AssemblyFileVersionAttribute 属性指定的版本号。如果程序集需要安装到 GAC，通过这种方式指定程序集的版本比较常见。

AutoDocumentConstructors

若此项为真，文档引擎将为类型的默认构造函数(即不附带参数的那个构造函数)添加默认的 summary 文档。

AutoPropertyBackerSummaries

若此项为真，文档引擎会把字段 _Length 或 length 视为属性 'Length' 的辅助字段，在 _Length 或 length 缺少文档信息时，自动为它添加 summary 信息(“属性 Length 的辅助字段。”)。

CleanIntermediates

是否在文档成功生成后，删除中间文件。
比如 MSDN 和 VS.NET 文档引擎会编译为单一文件，它们的中间文件包括所有编译前的网页、HTML Help 项目文件等。

CopyrightHref

版权声明文本的超链接地址。

CopyrightText

版权声明文本，将被输出到代码文档的每个页面中。

FeedbackEmailAddress

用户反馈接收 Email 地址。将在输出的代码文档每页的底部添加放置指向此 Email 地址的超链接。

Preliminary

若此项为真，文档引擎将在每个页面中添加红色的消息“[此文档为预发布版本，在未来版本中有可能改变。]”。

SdkDocLanguge

指示文档引擎应将 .NET Framework 标准类库中包含的类型的超链接指向哪种本地化语言版本的 .NET Framework SDK。

SdkDocVersion

指示文档引擎应将 .NET Framework 标准类库中包含的类型的超链接指向哪个版本的 .NET Framework SDK。

UseNamespaceDocSummaries

若此项为真，文档引擎将在每个命名空间中查找一个名为 NamespaceDoc 的类，并将它的 summary 信息作为这个命名空间的 summary，这个类本身不会出现在最终的代码文档中。
如果需要，您可以使用 #if ... #endif，配合条件编译常数，在最终 Release 程序集中排除 NamespaceDoc 类。

UseNDocXmlFile

主要用于调试用途，一般情况下请留空白。NDoc 会首先生成中间 XML 数据文件（可以使用 XML 文档引擎得到），然后通过 XLST 转换为各种 HTML 格式。如果希望创作自定义的文档引擎，可以将此选项配置为事先生成的一个 NDoc 中间 XML 数据文件，这样将提高您的调试效率。

属性(attribute)的输出

DocumentAttributes

是否输出类型和成员的属性(attribute)。

DocumentedAttributes

属性(attribute)输出的过滤。当 DocumentAttributes = true 时，此配置指示将输出哪些属性，其他属性被过滤掉。
请使用编辑器生成，有效的格式应为：

'<attribute-name-starts-with>,<property-to-show>,<property-to-show>|<attribute-name-starts-with>,<property-to-show>,<property-to-show>|(etc...)'

如果为空白，则输出全部属性。

DocumentInheritedAttributes

是否输出从基类中继承而来的属性(attribute)。如果 DocumentAttributes = false，则此配置被忽略。

ShowTypeIdInAttributes

是否在属性(attribute)输出时输出 TypeId 值。如果 DocumentAttributes = false，则此配置被忽略。

缺少文档时的输出

ShowMissingParams

缺少 <param> 参数文档时，是否输出红色的提示文本。

ShowMissingRemarks

缺少 <remarks> 备注文档时，是否输出红色的提示文本。

ShowMissingReturns

缺少 <returns> 返回值文档时，是否输出红色的提示文本。

ShowMissingSummaries

缺少 <summary> 概述文档时，是否输出红色的提示文本。

ShowMissingValues

缺少 <values> 属性值文档时，是否输出红色的提示文本。

XLinks
　HTML Help 1 直接使用 HTML <A> 标记表示超链接。Microsoft Help 2 引入了新的 XLinks 机制 (是微软对 W3C XLinks 的一个实现)，来表示指向其他文档集合的超链接。一个 XLink 很像 HTML <A> 链接，但包含额外的元数据用于表示复杂的链接。Microsoft Help 2 使用 XLinks 不直接使用路径/文件名，而根据在“索引”表中检索特定的关键字查找。

NDoc 为指向 .NET Framework 类型/成员的链接（包括成员列表中指向基类型的链接、以及使用 <see> 标记加入的指向 .NET Framework 或第三方类库中的类型/成员的显式链接），制作 XLinks 链接。下面是一个指向 System.Void 的示例 XLink:

<MSHelp:link

keywords="frlrfSystemVoidClassTopic"

indexMoniker="!DefaultAssociativeIndex"

namespace="ms-help://MS.NETFrameworkSDKv1.1.CHS">void</MSHelp:link>

上面 XLink 的三个属性指示了查找这个帮助主题的方法。属性 namespace 指示在哪个文档命名空间中查找(每个帮助文档集合都需要在机器中注册一个唯一的命名空间，如上面的 ms-help://MS.NETFrameworkSDKv1.1.CHS 表示 .NET Framework SDK 类库文档的帮助文档集合)。属性 indexMoniker 指示使用哪种类型的“索引”(Microsoft Help 2 索引可以有很多类型，其中，DefaultAssociativeIndex 常用于创建帮助主题之间的关联)。最后，keyword 指示要指向哪个帮助主题页面。

每个页面头部的嵌入 XML 数据岛中都包含若干 Keywords，您可以在 .NET Framework SDK 类库文档中查看 System.Void 页面中，包含如下的一行:

<MSHelp:Keyword Index="A" Term="frlrfSystemVoidMembersTopic"/>

这个 frlrfSystemVoidMembersTopic 就是在 .NET Framework SDK 类库文档中，用 DefaultAssociativeIndex 类型的“索引”中的 keyword。

链接到 .NET Framework SDK 类库文档
　指向到 .NET Framework SDK 类库文档的超链接，不需要您费心，NDoc 已经可以做的很好。您尽管从 .NET Framework 的基类型继承、创作您的子类型，或者使用 <see> 等标记加入这些链接，NDoc 自动处理这些关于 XLinks 的事情。

链接到第三方类库文档
　NDoc 允许您创建指向到第三方类库文档的超链接，不过也需要严格按照上面介绍的 XLinks 体制来做。首先找到该文档集合的命名空间，和要指向的帮助主题 HTML 页头部中的 keyword，做好准备。(如果那个文档集合也是用 NDoc 1.3 生成的，则页面头部的 XML 数据岛已经按要求写好了 keyword。)

因为 NDoc 只能找到子类型的父类型的名称，<see> 标记中最终 NDoc 看到的也只是要指向的类型/成员的完全名称；NDoc 不知道这些类型/成员的文档存在哪个文档集合中。您需要告诉 NDoc：哪些类型/成员的帮助文档在哪个文档命名空间，而另一些类型/成员在另一个文档命名空间，也就是各 .NET 类型/成员和 Microsoft Help 2 帮助文档命名空间之间的映射关系。这就需要您指定 NamespaceMappingFile 了（请参见 VS.NET 2003 文档引擎的 UseHelpNamespaceMappingFile 配置项）。NamespaceMappingFile 是一个 XML 文件，它必须符合 NamespaceMapping XSD 架构(请右击“另存为...”)。

<namespaceMap xmlns="urn:ndoc-sourceforge-net:documenters.NativeHtmlHelp2.schemas.namespaceMap">

<helpNamespace ns="ms-help://companyX.sharedhelpcollection">

<managedNamespace ns="CompanyX"/>

</helpNamespace>

<helpNamespace ns="ms-help://companyX.producthelpcollection">

<managedNamespace ns="CompanyX.Product1"/>

<managedNamespace ns="CompanyX.Product2"/>

</helpNamespace>

</namespaceMap>

NamespaceMappingFile 的 一个实例:

<?xml version="1.0" encoding="utf-8"?>
<namespaceMap xmlns="urn:ndoc-sourceforge-net:documenters.NativeHtmlHelp2.schemas.namespaceMap">
<helpNamespace ns="ms-help://MS.NETFrameworkSDKv1.1.CHS">
<managedNamespace ns="System" />
<managedNamespace ns="Microsoft" />
</helpNamespace>
</namespaceMap>

　上面的例子表示指向 System 和 Microsoft 命名空间的类型/成员的链接，将被指向 ms-help://MS.NETFrameworkSDKv1.1.CHS 帮助文档命名空间。

指定了 NamespaceMappingFile 之后，其他的工作都可以交给 NDoc 来做了。

与 Visual Studio .NET IDE 的集成

　.NET Framework SDK 类库文档的每一个页面的头部都有一个嵌入的 XML 数据岛。在 Microsoft 文档资源管理器中，这些 XML 数据岛用于创建索引，链接帮助主题，查找关键字，筛选帮助主题，以及很多其他功能。Visual Studio .NET IDE 中的“动态帮助”功能也依赖于这些嵌入的 XML 数据。以下是一个 XML 数据岛示例：

<xml>

<MSHelp:TOCTitle Title="Object Class"/>

<MSHelp:RLTitle Title="Object Class"/>

<MSHelp:Keyword Index="K" Term="Object class, about Object class"/>

<MSHelp:Keyword Index="A" Term="frlrfSystemObjectClassTopic"/>

<MSHelp:Keyword Index="F" Term="System.Object"/>

<MSHelp:Attr Name="DocSet" Value="NETFramework"/>

<MSHelp:Attr Name="TopicType" Value="kbSyntax"/>

<MSHelp:Attr Name="DevLang" Value="CSharp"/>

<MSHelp:Attr Name="DevLang" Value="VB"/>

<MSHelp:Attr Name="DevLang" Value="C++"/>

<MSHelp:Attr Name="DevLang" Value="JScript"/>

<MSHelp:Attr Name="DevLang" Value="VJ#"/>

<MSHelp:Attr Name="Technology" Value="WFC"/>

<MSHelp:Attr Name="Technology" Value="ManagedC"/>

<MSHelp:Attr Name="TechnologyVers" Value="kbWFC"/>

<MSHelp:Attr Name="TechnologyVers" Value="kbManagedC"/>

<MSHelp:Attr Name="Locale" Value="kbEnglish"/>

<MSHelp:Attr Name="DocSet" Value="NETCompactFramework"/>

<MSHelp:Attr Name="TechnologyVers" Value="kbProfile2NETCF"/>

<MSHelp:Attr Name="HelpPriority" Value="2"/>

</xml>

NDoc VS.NET 文档引擎同样创建这样的 XML 数据岛，以提高和 Microsoft 文档资源管理器以及 VS.NET IDE 的集成性。

要求

　尽管 NDoc 为每一帮助主题生成必要的 XML 数据岛，但要更好的利用 Microsoft Help 2 的功能（如筛选器等），还需要了解更多的背景知识。

Help Title 必须存在于一个帮助集合中。

Microsoft Help 2 定义了两个级别的帮助文档容器：Help Title 和帮助集合。Help Title 是一组相关的帮助主题，编译为一个 .HxS 文件。帮助集合是一个或多个 Help Title 的集合。(您可以这样理解：一个 Help Title 可以被当作一个帮助集合，但反过来不成立。) 每个帮助集合必须分配有一个唯一的命名空间。

只有帮助集合才能被集成到 VS.NET 的帮助系统中。

帮助集合必须在每台机器上注册后才能被访问。

Microsoft Help 2 帮助系统维护一个注册表(不要和 Windows 注册表混淆)，保存当前机器中所有已安装的帮助集合。此注册表用于定位超链接的目的地，执行检索，显示索引等。这是 Microsoft Help 2 中一个核心的部分。

因为这个原因，帮助集合必须在安装时注册到每台客户端机器中，否则将无法访问得到。

已注册的帮助集合可以被“plugged-in”进 VS.NET 合并文档集合。

Microsoft Help 2 允许帮助集合的插接。可以将您的帮助集合插接到其他已有的帮助集合中，比如 VS.NET 合并文档集合，它的命名空间是 MS.VSCC.2003。

还很糊涂？

　Microsoft Help 2 确实是一套复杂的技术。更深入的信息请查阅 VSHIK 文档。网站 helpware.net 提供了很多有关 Microsoft Help 2 的有用资料和教程。HelpWare 还提供了一个名为 FAR 的共享软件，它更证明了 Microsoft Help 2 帮助系统的潜力。

VS.NET 文档引擎使用了几个配置项，意在简化整个过程。

首先，您应该设置 GenerateCollectionFiles 为 true。这将指示 NDoc 将生成的文档合并到 VS.NET 合并文档集合中去。

然后，您需要指定 CollectionNamespace，帮助集合的命名空间名称。不要使用空格、汉字等 URI 中不允许的字符。建议您设法让这个命名空间名称不容易重复，比如以您的公司名开始，等等。

第三步，指定 PlugInNamespace。它表示要“plugged-in”到哪个文档集合中去。当使用 h2reg.exe 部署您的帮助文档时，它们被插接到 VS.NET 的合并文档集合中去。默认值 ms.vscc 指示 h2reg.exe 自动判断 VS.NET 是 2002 或 2003 版本。

筛选器

　每个帮助主题的 XML 数据岛中可以包含一个或多个 DocSet 值。在文档资源管理器及 VS.NET IDE 中，这些 DocSet 值常常被各个筛选器用于筛选帮助索引及搜索范围。

默认的一些筛选器定义如下:

Windows Client SDK, 　　Query: "DocSet"="WCSDK"
.NET Framework, 　　　　Query: ("DocSet"="NETFramework" OR "DocSet" = "NETFrameworkExtender") OR (("DocSet"="C#" OR "DocSet"="Visual Basic" OR "DocSet"="Visual C++" OR "DocSet"="VBA" OR "DocSet"="VJ#" OR "DocSet"="Visual Studio") AND "Technology"="ManagedCode")
Visual Studio 宏, 　　　Query: "DocSet" = "VSM" OR "DocSet" = "NETFramework"
Visual Basic, 　　　　　Query: "DocSet" = "Visual Basic" OR "DocSet" = "NETFramework" OR "DocSet" = "NETFrameworkExtender" OR "DocSet" = "DHTML" OR "DocSet" = "XML" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "kbVBp700")
Visual C++, 　　　　　　Query: "DevLang" = "C" OR "DevLang" = "C++" OR "Product" = "VC" OR "DocSet" = "PSDK" OR "DocSet" = "NETFramework" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "kbVC700")
Platform SDK, 　　　　　Query: "DocSet" = "PSDK"
(no filter), 　　　　　Query:
企业级服务器, 　　　　Query: "DocSet" = "NETEnterpriseServers" OR "DocSet" = "SQL Server"
Internet 开发,　　　　Query: "DocSet" = "DHTML" OR "DocSet" = "XML" OR "DevLang" = "DHTML" OR "DevLang" = "HTML" OR "DevLang" = "VBScript" OR "DevLang" = "JScript" OR "DevLang" = "ASP" OR "Technology" = "kbSOAP" OR "Technology" = "ASPNET" OR "Technology" = "HPS"
Visual Studio, 　　　Query: "DocSet" = "Visual Studio" OR "DocSet" = "Visual Studio SDK" OR "DocSet" = "CrystalReports" OR "DocSet" = "Visual Source Safe" OR "DocSet" = "VSAnalyzer" OR "DocSet" = "PSDK" OR "DocSet" = "NETFramework" OR "DocSet" = "NETFrameworkExtender" OR "DocSet" = "NETEnterpriseServers" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "kbVS700")
Visual C#, 　　　　　Query: "DocSet" = "C#" OR "DocSet" = "NETFramework" OR "DocSet" = "NETFrameworkExtender" OR "DocSet" = "DHTML" OR "DocSet" = "XML" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "C#")
Samples, Query: "TopicType"="kbSampleProd"
Visual FoxPro, 　　　Query: "DocSet" = "Visual FoxPro" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "kbVFP700")
Knowledge Base, 　　Query: "DocSet" = "kbKB"
Visual J#,　　　　 　Query: "DocSet" = "VJ#" OR "DocSet" = "NETFramework" OR "DocSet" = "NETFrameworkExtender" OR "DocSet" = "DHTML" OR "DocSet" = "XML" OR ("DocSet" = "kbmsdn" AND "ProductVers" = "VJ#")
.NET Framework 精简版, Query: "DocSet"="Smart Devices" OR "DocSet"="NetCompactFramework"
中文(简体)文档,　　　 Query: ("Locale"="kbChineseSimp")

将您的帮助集合加入上面这些筛选器的搜索范围，可以很简单的指定文档引擎的 DocSetList 配置项。它是一个逗号分隔的字符串，每一项最终都被写成 XML 数据岛中的一行 DocSet 值。当用户使用这些筛选器时，如果您的帮助页面 XML 数据岛中具有特定的 DocSet 值，您的帮助文档就会被包括在搜索范围中。

NDoc 默认将 HtmlHelpName 作为一行 DocSet 值写入每页的 XML 数据岛。您不需要通过 DocSetList 重复定义它。

NDoc 默认会注册一个新的筛选器，这个筛选器的查询条件是 "DocSet" = "HtmlHelpName"，即这个筛选器将只搜索这个帮助集合的内容。Microsoft Help 2 允许您定义其他自定义的筛选器，但已经超出 NDoc 的工作范围，您需要自行查阅 VSHIK 文档，修改 Microsoft Help 2 项目文件重新编译。

部署 Microsoft Help 2

　Microsoft Help 2 帮助系统维护一个注册表(不要和 Windows 注册表混淆)，保存当前机器中所有已安装的帮助集合。注册表保存了所有的帮助集合，每个帮助集合中包含的 Help Titles，帮助集合间的嵌套关系等。

查看 Microsoft Help 2 Title 或集合之前，必须首先注册。因此 Microsoft Help 2 文档的部署，要比 HTML Help 1 的简单文件拷贝复杂的多。

Windows Installer
　可以通过创建一个 Windows Installer 安装包程序，用于部署并注册帮助集合和 Help Titles。VSHIK 文档中有具体的制作步骤。不幸的是，这个过程中有很多手工的步骤，我们还没有能够找到自动制作 Windows Installer 安装包的方法。

H2Reg
　另一格选择是使用 helpware.net 提供的 共享软件 H2Reg.exe。H2Reg.exe 是一个命名行工具，可以在安装过程中使用它，完成帮助集合/Help Title 的注册。它可以被用于任何支持命令行的安装程序，比如对于 Windows Installer 安装包，H2Reg 可以作为一个自定义动作。

如果设置 GenerateCollectionFiles 为 true，NDoc 会为 H2Reg 创建特定的 INI 配置文件，H2Reg 可以根据这个 INI 配置文件完成 Help Title 的注册、并合并到 VS.NET 的合并文档集合等动作。(记得将这个 INI 配置文件包含进您的安装包。)

下面是完整的步骤:

1. 设置文档引擎的 GenerateCollectionFiles 为 true
2. 将编译生成的帮助文件(*.HxS, *.HxI 等)，和生成的 INI 文件包含到安装包中。
3. 将 H2Reg.exe 和 H2Reg.ini (此文件可以从 H2Reg 安装路径中拷贝出来)包含到安装包中。
4. 配置安装包，让安装包安装时，将帮助文件和生成的 INI 文件复制到安装路径下。
5. 安装动作：执行 H2Reg，语法为:
   H2reg -r "CmdFile=<生成的 INI 文件的完整路径>"
6. 卸载动作：执行 H2Reg，语法为:
   H2reg -u "CmdFile=<生成的 INI 文件的完整路径>"

注意: 先执行 H2Reg，再删除相应的帮助文件和 INI 文件。

概述
　MSDN 文档引擎用于生成如 .NET Framework SDK 类库文档样式的代码文档，并编译为 HTML Help 1 格式的单一文件(*.CHM)。

MSDN 2003 文档引擎是 NDoc 1.3 对 MSDN 文档引擎的改进，加入了语言选择器等功能，更加接近 .NET Framework SDK 文档的样式。

配置
　所有文档引擎都具有一些 通用的配置项。

配置项	说明
AdditionalContentResourceDirectory	页面中涉及到的资源文件（如图片等）所在的目录。此目录及其子目录中的所有文件，将以原有的目录结构包含进 HTML Help 项目中，使用相对路径的超链接不需要做大的调整。 注意: 此文件夹中第一层次的文件，和 NDoc 生成的 HTML 文件、以及通过 FilesToInclude 包含进来的文件，将处在同一层次上，请依次类推其他文件的相对 URL。
BinaryTOC	是否以二进制方式创建目录树文件。这将显著提高大尺寸 CHM 文件的打开速度。
ExtensibilityStylesheet	用户自定义的 NDoc 扩展 XSLT 转换文件，用于转换用户自定义的特殊标记。请参见 NDoc 可扩展性。
FilesToInclude	指定需要包含在 HTML Help 项目中的附加文件。(1)允许使用绝对路径或相对路径指定，相对路径相对于 NDoc 项目文件所在目录。(2)可以使用通配符 * 和 ?，如 D:\preparedDocs\*.html。(3)可以有多个地址，用符号 "|" 隔开。
FooterHtml	自定义的 HTML 页脚。您可以直接使用 HTML 代码，其中: "%FILE_NAME%" 将被自动替换为页面的文件名，"%TOPIC_TITLE%" 被替换为该页面的标题文字，"%ASSEMBLY_NAME%" 和 "%ASSEMBLY_VERSION%" 分别被替换为当前页面对应类型所属程序集的名称和版本信息。
HeaderHtml	自定义的 HTML 页头。您可以直接使用 HTML 代码，其中: "%FILE_NAME%" 将被自动替换为页面的文件名，"%TOPIC_TITLE%" 则被替换为该页面的标题文字。
HtmlHelpName	一个名称，用于命名生成的 HTML Help 项目以及将要生成的 CHM 文件。
IncludeFavorites	是否在生成的 HTML Help 文件中包含“收藏”选项卡。
LangID HTML Help	文件的 LangID 设置。中文版默认为 2052。
OutputDirectory	输出文件目录，生成的 .html 和 .chm 文件都将存放于此目录。
OutputTarget	输出目标格式: HTML Help (.chm) 或 Web 网页或两者都输出。
RootPageContainsNamespaces	如果为真，RootPageFileName指定的主页面，将在目录树中表示为所有命名空间结点的容器（父结点）。否则，将和其他命名空间结点并列表示。
RootPageFileName	通过此项指定 HTML Help 文件中的主页面文件名。注：此处主页指打开 CHM 文件时显示的第一个页面，请通过 RootPageTOCName 指定此主页面在目录树中的显示名称；通过 RootPageContainsNamespaces 指定此主页面在目录树中的显示样式；可以通过 FilesToInclude 将此文件引入到此 HTML Help 项目中来。
RootPageTOCName	HTML Help 文件中，主页在目录树中的显示名称。若 RootPageFileName 指定了某一页面，而此项没有指定，则将在目录树中显示“概述”作为名称。注：此处主页指打开 CHM 文件时显示的第一个页面。
SdkLinksOnWeb	如果为真，类库中所有指向 .NET Framework 标准类库的文档超链接都将指向 MSDN 的在线版本。否则，将指向本地版本。
ShowVisualBasic	是否为类型和成员显示 Visual Basic 语法块。
Title	此文本将显示在每个页面的左上角，一般填写类库的名称比较合适。

将附加的文件加入要编译的 CHM 文件中

　MSDN 文档引擎提供了 FilesToInclude 和 AdditionalContentResourceDirectory 两种途径，允许您附加额外的文件。

前者允许您使用 * 或 ? 通配符的形式指定要包含的文件路径，可以指定多个路径，用“|”隔开。如果使用相对路径，应相对于 NDoc 项目文件所在的目录。注意：在最终编译的 CHM 中，这些被附加的文件，和其他由 NDoc 生成的 HTML 文件，处在同一级目录中。

后者将一个文件夹中的内容(包括子文件夹中的全部内容)全部读入。注意：在最终编译的 CHM 中，AdditionalContentResourceDirectory 文件夹第一级的文件和文件夹，和其他由 NDoc 生成的 HTML 文件，处在同一级目录中；该目录的子目录及其中内容，将保持原有父子关系。例如 AdditionalContentResourceDirectory 是 D:\temp ，这个目录中有 my.css 文件和 images 子目录，images 目录中有 logo.gif 文件，则 my.css 和其他 NDoc 生成的文件同级，使用相对路径引用 my.css 时为“my.css”；而引用 logo.gif 应为“images/logo.gif”。

请根据您的具体情况进行选择具体采用哪种方式。

另外，RootPageFileName 指定 CHM 打开时的第一个页面文件，这个页面可以是 NDoc 生成的文件，也可以是通过上述两种方式附加进去的某 HTML 文件。

概述
　MSDN 2003 文档引擎是 NDoc 1.3 对 MSDN 文档引擎的改进，加入了语言选择器等功能，更加接近 .NET Framework SDK 文档的样式。它用于生成如 .NET Framework SDK 类库文档样式的代码文档，并编译为 HTML Help 1 格式的单一文件(*.CHM)。

配置
　所有文档引擎都具有一些 通用的配置项。

配置项	说明
AdditionalContentResourceDirectory	页面中涉及到的资源文件（如图片等）所在的目录。此目录及其子目录中的所有文件，将以原有的目录结构包含进 HTML Help 项目中，使用相对路径的超链接不需要做大的调整。 注意: 此文件夹中第一层次的文件，和 NDoc 生成的 HTML 文件、以及通过 FilesToInclude 包含进来的文件，将处在同一层次上，请依次类推其他文件的相对 URL。
BinaryTOC	是否以二进制方式创建目录树文件。这将显著提高大尺寸 CHM 文件的打开速度。
ExtensibilityStylesheet	用户自定义的 NDoc 扩展 XSLT 转换文件，用于转换用户自定义的特殊标记。请参见 NDoc 可扩展性。
FilesToInclude	指定需要包含在 HTML Help 项目中的附加文件。(1)允许使用绝对路径或相对路径指定，相对路径相对于 NDoc 项目文件所在目录。(2)可以使用通配符 * 和 ?，如 D:\preparedDocs\*.html。(3)可以有多个地址，用符号 "|" 隔开。
FooterHtml	自定义的 HTML 页脚。您可以直接使用 HTML 代码，其中: "%FILE_NAME%" 将被自动替换为页面的文件名，"%TOPIC_TITLE%" 被替换为该页面的标题文字，"%ASSEMBLY_NAME%" 和 "%ASSEMBLY_VERSION%" 分别被替换为当前页面对应类型所属程序集的名称和版本信息。
HeaderHtml	自定义的 HTML 页头。您可以直接使用 HTML 代码，其中: "%FILE_NAME%" 将被自动替换为页面的文件名，"%TOPIC_TITLE%" 则被替换为该页面的标题文字。
HtmlHelpName	一个名称，用于命名生成的 HTML Help 项目以及将要生成的 CHM 文件。
IncludeFavorites	是否在生成的 HTML Help 文件中包含“收藏”选项卡。 LangID HTML Help 文件的 LangID 设置。中文版默认为 2052。
OutputDirectory	输出文件目录，生成的 .html 和 .chm 文件都将存放于此目录。
OutputTarget	输出目标格式: HTML Help (.chm) 或 Web 网页或两者都输出。
RootPageContainsNamespaces	如果为真，RootPageFileName 指定的主页面，将在目录树中表示为所有命名空间结点的容器（父结点）。否则，将和其他命名空间结点并列表示。
RootPageFileName	通过此项指定 HTML Help 文件中的主页面文件名。注：此处主页指打开 CHM 文件时显示的第一个页面，请通过 RootPageTOCName 指定此主页面在目录树中的显示名称；
RootPageContainsNamespaces	指定此主页面在目录树中的显示样式；可以通过 FilesToInclude 将此文件引入到此 HTML Help 项目中来。
RootPageTOCName	HTML Help 文件中，主页在目录树中的显示名称。若
RootPageFileName	指定了某一页面，而此项没有指定，则将在目录树中显示“概述”作为名称。注：此处主页指打开 CHM 文件时显示的第一个页面。
SdkLinksOnWeb	如果为真，类库中所有指向 .NET Framework 标准类库的文档超链接都将指向 MSDN 的在线版本。否则，将指向本地版本。
Title	此文本将显示在每个页面的左上角，一般填写类库的名称比较合适。

将附加的文件加入要编译的 CHM 文件中
　MSDN 文档引擎提供了 FilesToInclude 和 AdditionalContentResourceDirectory 两种途径，允许您附加额外的文件。

前者允许您使用 * 或 ? 通配符的形式指定要包含的文件路径，可以指定多个路径，用“|”隔开。如果使用相对路径，应相对于 NDoc 项目文件所在的目录。注意：在最终编译的 CHM 中，这些被附加的文件，和其他由 NDoc 生成的 HTML 文件，处在同一级目录中。

后者将一个文件夹中的内容(包括子文件夹中的全部内容)全部读入。注意：在最终编译的 CHM 中，AdditionalContentResourceDirectory 文件夹第一级的文件和文件夹，和其他由 NDoc 生成的 HTML 文件，处在同一级目录中；该目录的子目录及其中内容，将保持原有父子关系。例如 AdditionalContentResourceDirectory 是 D:\temp ，这个目录中有 my.css 文件和 images 子目录，images 目录中有 logo.gif 文件，则 my.css 和其他 NDoc 生成的文件同级，使用相对路径引用 my.css 时为“my.css”；而引用 logo.gif 应为“images/logo.gif”。

请根据您的具体情况进行选择具体采用哪种方式。

另外，RootPageFileName 指定 CHM 打开时的第一个页面文件，这个页面可以是 NDoc 生成的文件，也可以是通过上述两种方式附加进去的某 HTML 文件。
　
　 概述
　XML 文档引擎是 NDoc 中最简单的文档引擎，它直接输出 NDoc 生成的中间 XML 文件。主要帮助开发人员调试 NDoc 扩展 XSLT 转换，以及制作新的自定义文档引擎。

请参见 NDoc 可扩展性 和 实现一个新的文档引擎。

配置
　所有文档引擎都具有一些 通用的配置项。

配置项	说明
OutputFile	输出 XML 文件名。XML 文档引擎输出 NDoc 文档生成器所使用的中间 XML 格式数据，适用于自定义文档引擎的制作与调试。

概述
　JavaDoc 文档引擎用于创建类似 JavaDoc (Java 社区中，自动创建代码文档的工具) 布局和格式的 HTML 代码文档。

因为缺少足够的关注度，此文档引擎的开发并不活跃。 如果您有兴趣进一步完善此文档引擎，请联络 NDoc 项目管理员。

配置
　所有文档引擎都具有一些 通用的配置项。

配置项	说明
Title JavaDoc	项目标题。
OutputDirectory	存放输出 HTML 文件的文件夹。 可以为绝对路径或者相对于 NDoc 项目文件的相对路径。

概述
　Linear HTML 文档引擎用于生成单一 HTML 文件的代码文档。

配置
　所有文档引擎都具有一些 通用的配置项。

配置项	说明
OutputDirectory	目标 HTML 文件的输出目录。
Title	HTML 页的标题。
IncludeTypeMemberDetails	是否输出类型成员的细节（如：是否显示字段、属性的“备注”等，是否单独显示方法的参数表格）
MethodParametersInTable	是否在同一表格中显示方法的参数列表。
TypeIncludeRegexp	一个正则表达式，设置此项可以过滤类型的输出，只有符合正则表达式的类型被输出。留空白则输出全部。
amespaceExcludeRegexp	一个正则表达式，设置此项可以过滤命名空间的输出，符合正则表达式的命名空间被过滤。留空白则关闭过滤。

概述
　LaTeX 文档引擎用于创建 dvi、pdf、postscript 等 LaTeX 格式的代码文档。

您需要安装一个 LaTeX 编译器，比如免费的 MiKTeX。关于 LaTeX 的中文支持问题，请参见 CTeX: 中文 TeX 网站 中的相关内容。

配置
　所有文档引擎都具有一些 通用的配置项。

配置项	说明
OutputDirectory	文件输出目录。
LatexCompiler LaTeX	编译器路径。(如果您没有安装 LaTeX 编译器，请保持空白。)
TexFileBaseName	目标 LaTeX 文件名，请不要加扩展名。

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 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。

下面的表格显示了各 block 标记的有效性。

　<c> 标记指示将其内部的文本表示为代码样式，Inline 标记，用于表示行文中的代码片断。

<c>text</c>
　其中:

text
　要标记为代码样式的文本。
　应用于
　可用于其他标记内部。

备注
　如果需要标记多行的代码块，请使用 <code> 标记。

示例
　[C#]
　public class MyClass
　{
　/// <summary>
　/// <c>MyMethod</c> is a method in the <c>MyClass</c> class.
　/// </summary>
　public static void MyMethod(int Int1)
　{
　}
　}

　 <code> 标记指示将其内部的文本表示为代码样式，Block 标记，用于表示多行的代码块。

<code [lang="language"][escaped="true"]>content</code>
　其中:

lang="language" [NDoc 扩充]
　语言选择器，表示此代码块仅适用于某种编程语言。(可选)
　escaped="true" [NDoc 扩充]
　若 content 中含有 XML 子级，将它们视为代码的一部分。注意：content 仍然需要是格式完好的 XML。(可选)
　content
　将被表示为代码块的文本。
　应用于
　可用于其他 Section 标记或 Block 标记内部。

备注
　使用 lang 属性表示语言选择器，标准的语言有: Visual Basic, C#, C++ 及 JScript。若代码块适用于多种语言，则用逗号隔开，比如“Visual Basic, C#, C++”。

escaped 为 true 时，其内部所有其他标记都被转义为代码块的一部分。

注意 content 内容必须是格式完好的 XML 注释。否则整个注释块可能被忽略或出错!!!

示例
　下面示例中，因为 escaped="true"，因此直接写入了要作为代码块的 XML 内容。 Note how, in the following comments, the xml text can entered verbatim because the escaped="true" attribute has been applied.

[C#]
　/// <summary>
　/// Loads the XML.
　/// </summary>
　/// <example> The XML should have the following format.
　/// <code escaped="true">
　/// <root>
　/// <member name="name"/>
　/// </root>
　/// </code>
　/// </example>
　public void LoadXml(string xml)
　{
　//do something here...
　}

<event> 标记用于说明被标记的方法可能引发的事件。Section 标记。

<event cref="member">description</event>
　其中:

cref = "member"
　表示可能引发的事件。书写时，如果可能引发的事件是同一类型的事件，member 可以直接写事件名称（注意大小写）；如果是其他类型的，建议您写该事件的完全限定名称。C# 编译器将检查该事件是否存在。在输出的 XML 文档文件中，C# 编译器会自动转换简写的 member 为完全限定名称。
　description
　附加的说明，比如在什么情况下引发该事件。
　应用于
　方法成员。

备注

示例

　 <example> 标记表示“示例”区域。Section 标记。用于书写能辅助使用者理解并快速上手的示例代码等内容。

<example>description</example>
其中:

description
示例及其说明。
应用于
所有的类型及成员。

备注
此标记经常和 <code> 标记联用。

示例
[C#]
public class MyClass
{
/// <summary>
/// The GetZero method.
/// </summary>
/// <example> This sample shows how to call the GetZero method.
/// <code>
/// class MyClass
/// {
/// public static int Main()
/// {
/// return GetZero();
/// }
/// }
/// </code>
/// </example>
public static int GetZero()
{
return 0;
}
}

<exception> 标记用于说明一个成员可能抛出的异常。

<exception cref="member">description</exception>
其中:

cref = "member"
表示可能抛出的异常类型。书写时，如果可能抛出的异常是同一命名空间下的异常类型，member 可以直接写异常名称（注意大小写）；如果是其他命名空间的，建议您写该异常类型的完全限定名称。C# 编译器将检查该异常是否存在。在输出的 XML 文档文件中，C# 编译器会自动转换简写的 member 为完全限定名称。
description
说明信息，比如在什么情况下抛出该异常。
应用于
属性, 方法, 事件, 运算符, 类型转换

备注

示例
[C#]
using System;

/// comment for class
public class EClass : Exception
{
// class definition ...
}

class TestClass
{
/// <exception cref="EClass">Thrown when... .</exception>
public static void Main()
{
...
throw new EClass();
...
}
}

<exclude/> 标记指示 NDoc 文档引擎将被标记的类型/成员排除在代码文档之外。

<exclude/>
应用于
所有的类型及成员。

备注
与文档引擎的“可见性”配置不符的，以 exclude 优先。

示例
请参见

<include> 标记指示将代码文件(*.cs)外部的某 XML 文件中的一部分、作为 XML 文档注释、包含进代码文件来。

<include file='filename' path='tagpath[@name="id"]' />
其中:

filename
包含 XML 文档注释的文件名。该文件名可包含路径。将 filename 括在单引号中 (' ')。
tagpath
filename 中指向标记名的标记路径（使用 XPath 语法）。将此路径括在单引号中 (' ')。
name
注释前边的标记中的名称说明符；名称具有一个 id。
id
位于注释之前的标记的 ID。将此 ID 括在双引号中 (" ")。
应用于
所有的类型及成员。

备注
这是除了将文档注释直接置于源代码文件中之外的另一种可选方法。

<include> 标记使用 XML XPath 语法。有关自定义 <include> 使用的方法，请参见 XPath 文档。

示例
以下是一个多文件示例。第一个文件使用 <include>，如下所列：

[C#]
/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
class Test
{
public static void Main()
{
}
}

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
class Test2
{
public void Test()
{
}
}
第二个文件 xml_include_tag.doc 包含下列文档注释：

<MyDocs>

<MyMembers name="test">
<summary>
The summary for this type.
</summary>
</MyMembers>

<MyMembers name="test2">
<summary>
The summary for this other type.
</summary>
</MyMembers>

</MyDocs>
编译器输出的 XML 文档
<?xml version="1.0"?>
<doc>
<assembly>
<name>t2</name>
</assembly>
<members>
<member name="T:Test">
<summary>
The summary for this type.
</summary>
</member>
<member name="T:Test2">
<summary>
The summary for this other type.
</summary>
</member>
</members>
</doc>

　 <list> 标记表示一个列表(数字列表或符号列表)，或一个表格，或一个定义表。Block 标记。

<list type="bullet" | "number" | "table" | "definition">
<listheader>
<term>term</term>
<description>description</description>
</listheader>
<item>
<term>term</term>
<description>description</description>
</item>
</list>
其中:

term
要定义的项，该项将在 description 中说明/定义。
description
对 term 的说明/定义。
备注
<list> 可以表示为四种样式：bullet 为符号列表，即对应于 HTML 中的 UL 列表；number 为数字列表，即对应于 HTML 中的 OL 列表；table 为表格，将以表格形式表示；definition 为定义列表，显示效果就像本页上方“其中”二字下面对 term 和 description 的定义那样。

<listheader> 对 table 和 definition 有效。对 table，需要为 term 和 description 两列分别指定列标题。对 definition，需要指定标题文本，如本页上方的“其中:”那一行。

<item> 块表示列表中的一项。item 包含子元素 term 和 description。对 bullet 和 number 列表，term 无效也不需要写。对 table 表，可以没有 term，只写 description。对 definition 表，term 和 description 都应该有。

列表可以根据需要包含多个 <item> 块。

示例

　 <note> 标记表示一个“注意”块。

<note type="caution" | "inheritinfo" | "implementnotes">
description
</note>

其中:

description
注意事项。
应用于
可用于其他标记内部。

备注
caution 将显示为“警告”，inheritinfo 将显示为“对继承者的说明”，implementnotes 将显示为“对实施者的说明”。

示例

　 <overloads> 标记为“重载列表”页面提供文档。

简单语法
<overloads>
summary_description
</overloads>

复合语法
<overloads>
<summary>summary_description</summary>
[<remarks>remarks_description</remarks>]
[<example>examples_description</example>]
</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) { ... }

<para> 标记表示一个段落。

<para [lang="language"]>content</para>
where:

lang="language" [NDoc 扩充]
表示语言选择器，指示此段落仅对某种编程语言有效。(可选)
content
段落文本。
应用于
可用于其他标记内部。

备注
此标记经常用于 <summary>, <remarks>, 及 <returns> 等标记内部。

使用 lang 属性表示语言选择器，标准的语言有: Visual Basic, C#, C++ 及 JScript。若代码块适用于多种语言，则用逗号隔开，比如“Visual Basic, C#, C++”。

示例
请参见 <summary> 的示例。

The <param> tag describes one of the parameters for the method.

<param name='name'>description</param>
where:

name
The name of a method parameter. Enclose the name in single quotation marks (' ').
description
A description for the parameter.
Applies To
Property, Method, Event, Operator.

Remarks
Example
[C#]
/// text for class MyClass
public class MyClass
{
/// <param name="Int1">Used to indicate status.</param>
public static void MyMethod(int Int1)
{
}
/// text for Main
public static void Main ()
{
}
}
See Also

　 <paramref> 标记引用一个参数，将以代码样式表示该参数名称。

<paramref name="name"/>
其中:

name
参数的名称。
应用于
可用于其他标记内部。

备注
示例
[C#]
/// text for class MyClass
public class MyClass
{
/// <remarks>MyMethod is a method in the MyClass class.
/// The <paramref name="Int1"/> parameter takes a number.
/// </remarks>
public static void MyMethod(int Int1)
{
}

/// text for Main
public static void Main ()
{
}
}

　 <permission> 标记说明访问某成员所必需的 .NET Framework 安全性 CodeAccessPermission。

<permission cref="member">description</permission>
其中:

cref = "member"
表示需要的 CodeAccessPermission 类型。书写时，如果 CodeAccessPermission 是同一命名空间下的类型，member 可以直接写其名称（注意大小写）；如果是其他命名空间的，建议您写该 CodeAccessPermission 的完全限定名称。C# 编译器将检查该 CodeAccessPermission 是否存在。在输出的 XML 文档文件中，C# 编译器会自动转换简写的 member 为完全限定名称。
description
其他说明。
应用于
所有成员。

备注
System.Security.PermissionSet 使您得以指定对成员的访问。

示例
[C#]
using System;
class TestClass
{
/// <permission cref="System.Security.PermissionSet">Everyone can access this method.</permission>
public static void Test()
{
}
public static void Main()
{
}
}
　
　 <preliminary> 标记将类型/成员标记为“预发布”。

<preliminary>[description]</preliminary>
其中:

description
对“预发布”的说明文本。(可选)
应用于
所有的类型及成员。

备注
若没有指定 description，则以红色显示默认的文本: “[此文档为预发布版本，在未来版本中有可能改变。]”

如果需要把全部类型/成员都标记为“预发布”，请使用文档引擎的 Preliminary 配置项。

示例
[C#]
// The class summary will get the default message
/// <preliminary/>
public class MyClass
{
/// <preliminary>
/// <para>This method is just for testing right now. It might be removed in the near future</para>
/// </preliminary>
public void Dump ()
{
}
}

　 <remarks> 标记表示对类型或成员的“备注”。

<remarks>description</remarks>
其中:

description
对类型/成员的“备注”。
应用于
所有的类型及成员。

备注
<remarks> 标记用于对 <summary> 摘要信息的补充。.

示例
[C#]
/// <summary>
/// You may have some primary information about this class.
/// </summary>
/// <remarks>
/// You may have some additional information about this class.
/// </remarks>
public class MyClass
{
/// text for Main
public static void Main ()
{
}
}

　 <returns> 标记用于说明方法的返回值。

<returns>description</returns>
其中:

description
对方法的返回值的说明。
应用于
方法。

备注
示例
[C#]
/// text for class MyClass
public class MyClass
{
/// <returns>Returns zero.</returns>
public static int GetZero()
{
return 0;
}

/// text for Main
public static void Main ()
{
}
}

　 <see> 标记用于在行文中添加一个超链接。

<see cref="member">[label]</see>
或
<see href="URL">[label]</see>
或
<see langword="null | sealed
| static | abstract | virtual | true | false"/>
其中:

label
超链接的显示文本。
cref = "member"
表示要链接到的类型(成员)。书写时，如果要链接到的类型(成员)是同一命名空间(类型)中的类型(成员)，member 可以直接写它的名称（注意大小写）；如果是其他命名空间(类型)的，建议您写该类型(成员)的完全限定名称。C# 编译器将检查该类型(成员)是否存在。在输出的 XML 文档文件中，C# 编译器会自动转换简写的 member 为完全限定名称。
href = "URL" [NDoc 扩充]
一个网络 URL 地址。
langword [NDoc 扩充]
将会被当作 .NET 关键字粗体显示。如果 langword 是下面备注中的表格里的某个关键字，还将会被替换为相应的说明文本。
应用于
可用于其他标记内部。

备注
　使用 <seealso> 标记将超链接加入到页面的“请参见”区域。

注意: 在 NDoc 1.3 中，对于 MSDN 和 VS.NET 文档引擎，如果一个区域出现了多个指向同一个类型/成员的文档的 <see>，则只转换第一个为超链接，其余的不表示为超链接、只显示为粗体。这将使页面不至于太杂乱。

可识别的 langword
　如果 langword 为下表中的关键字之一，则会显示右侧相应的说明文本。

langword	显示
null	空引用(Visual Basic 中为 Nothing)
sealed	密封的(Visual Basic 中为 NotInheritable)
static	静态(Visual Basic 中为 Shared)
abstract	抽象(Visual Basic 中为 MustInherit)
virtual	虚拟(Visual Basic 中为 CanOverride)

示例
　请参见 <summary> 中的示例。

<seealso> 标记用于在页面的“请参见”区域添加一个超链接。

<seealso cref="member">[label]</seealso>
或
<seealso href="URL">[label]</seealso>
其中:

label
超链接的显示文本。
cref = "member"
表示要链接到的类型(成员)。书写时，如果要链接到的类型(成员)是同一命名空间(类型)中的类型(成员)，member 可以直接写它的名称（注意大小写）；如果是其他命名空间(类型)的，建议您写该类型(成员)的完全限定名称。C# 编译器将检查该类型(成员)是否存在。在输出的 XML 文档文件中，C# 编译器会自动转换简写的 member 为完全限定名称。
href = "URL" [NDoc 扩充]
一个网络 URL 地址。
应用于
所有的类型及成员。

备注
使用 <see> 标记在行文中添加超链接。

请不要将此标记包含在 <remarks> 标记内部。

示例
请参见 <summary> 中的示例。

<summary> 标记用于对类型或成员的摘要说明。

<summary>description</summary>
其中:

description
对类型或成员的摘要说明。
应用于
所有的类型及成员。

备注
此标记是所有类型及成员最基本的说明，一般的，应为每个公共的、可见的类型/成员书写 summary 文档。在 Visual Studio .NET IDE 的智能感知功能及对象查看器，还有其他大多数开发工具，都会显示 summary 信息。

<remarks> 标记用于更详细的说明。

示例
[C#]
/// text for class MyClass
public class MyClass
{
/// <summary>MyMethod is a method in the MyClass class.
/// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine"/> for information about output statements.</para>
/// <seealso cref="MyClass.Main"/>
/// </summary>
public static void MyMethod(int Int1)
{
}

/// text for Main
public static void Main ()
{
}
}

　 <threadsafety> 标记用于说明类型在多线程环境中是否安全。
<threadsafety static="true|false" instance="true|false"/>
其中:

static="true|false"
指示类型的静态成员在多线程环境中是否是安全的。
instance="true|false"
指示类型的实例成员在多线程环境中是否是安全的。
应用于
类, 结构。

备注
示例
[C#]
/// <threadsafety static="true" instance="false"/>
public class MyClass
{
/// not safe across threads
public void InstanceMethod()
{
}

/// safe across threads
public static void StaticMethod()
{
}
}

<value> 标记用于说明属性的值。

<value>property-description</value>
其中:

property-description
对属性值的说明。
应用于
属性。

备注
按照约定，总是应该为属性书写 <value> 标记。

示例
[C#]
/// text for class MyClass
public class MyClass
{
/// <summary>MyProperty is a property in the MyClass class.</summary>
/// <value>A string containing the text "MyProperty String".</value>
public string MyProperty()
{
get
{
return "MyProperty String";
}
}

}

NDoc 可扩展性
MSDN, MSDN 2003 和 VS.NET 文档引擎都支持一个可扩展的模型，允许您定义自己专有的标记，并指定它们在代码文档中呈现的样式。您或许已经知道，这些文档引擎都使用 XSLT 转换，将 NDoc 中间 XML 数据文件转换为目标 HTML 格式。NDoc 标记的可扩展性也依赖于此，您可以通过自定义的 XSLT 转换文件加入您自定义的标记。（建议，您需要事先了解一些 XSLT 转换的知识，并分析 XML 文档引擎生成的 NDoc 中间 XML 数据文件中的 XML 格式，经过足够的测试，以调试您自己的扩展 XSLT 转换。）

第一步，是在您的 C# 代码中加入您的自定义标记: (注意红色的自定义标记)

[C#]
/// <myTag>This is a custom tag</myTag>
/// <summary>
/// When processed by the VS.NET or MSDN documenters,
/// using the stylesheet "extend-ndoc.xslt" as the ExtensibilityStylesheet
/// property will result in end-user defined tags being displayed in the
/// final help output topics
/// </summary>
/// <remarks>This is a test of an inline <null/> tag</remarks>
public class ABunchOfCustomTags
{
}

在编译后生成的 /doc 文档中，您可以找到这些自定义的标记。

接下来，创建您的 XSLT 转换模板，控制那些自定义标记的输出位置和样式:

<xsl:stylesheet version="1.0" xmlns:xsl=http://www.w3.org/1999/XSL/Transform xmlns:MSHelp="http://msdn.microsoft.com/mshelp">

<xsl:template match="node()" mode="xml-data-island" priority="1">

<MSHelp:Attr Name="TargetOS" Value="Windows"/>

</xsl:template>

<xsl:template match="ndoc" mode="header-section">

<style type="text/css">

.green

{

color:green;

}

</style>

</xsl:template>
<xsl:template match="myTag" mode="seealso-section">

<h1 class="green">

<xsl:value-of select="." mode="slashdoc"/>

</h1>

</xsl:template>

<xsl:template match="null" mode="slashdoc">

<xsl:text> null reference (Nothing in Visual Basic) </xsl:text>

</xsl:template>

</xsl:stylesheet>

您应该确认 XSLT 标记的完整和语法的正确，注意 XSLT namespace 是必须的。

如上面示例中看到的那样，使用 stylesheet 中的 templates“匹配(match)”您的自定义标记。match 是 XPath 查询的一种，指示 template 将应用于哪些标记。简单的用法是直接匹配您的自定义标记，当然还可以有更高级的用法，对 XSLT 高手们应当是小菜一碟。

注意: 如果您定义的自定义标记中还包含其他标记，您应当加入下面的命令，让它转换这些内含的标记(比如 <see> 等)：
<xsl:apply-templates select="." mode="slashdoc"/>
上例中还展示了向 HTML HEAD 头部添加附加样式定义的方法，即使用 mode 为 header-section 的 template。使用这种方法您可以覆盖 NDoc 默认的样式或者添加附加的样式表等。

什么是 mode 呢？mode 用于指定该内容将显示于文档的哪些区域。NDoc 扩展的自定义标记可以是以下两类:

Section 标记 - 块标记，将显示于文档的某个区域。为 section 标记编写 template 时，mode 必须是预定义的可用 Section 的列表中的一个。
Inline 标记 - 将和其他注释文本夹杂在一起。为 inline 标记编写 template 时，mode 必须是 "slashdoc"。
如果您准备编写匹配一些泛型 XPath 查询，如 node(), text(), *, 或 @*，您应当给该 template 指定一个名为 priority、值大于 0.5 的属性，用您编写的 template 替换 NDoc 默认的转换模板。

请注意: XSLT 是大小写敏感的，match 查询模式，以及 mode 值都必须使用正确的大小写，否则将被忽略。

最后，为 MSDN 或 VS.NET 文档引擎设置 ExtensibilityStylesheet 配置，指向您创作好的 XSLT 转换文件。然后使用 NDoc 生成代码文档，您将看到已经按照您编写的 template 规则执行了相应转换。

一张屏幕截图:

输出示例

可用 Section 的列表
下面列出了所有可用 section 的清单，它们用于 NDoc 扩展 XSLT 转换模板中 mode 属性的值，指示该标记将显示在代码文档中的区域。

Section 名称	说明
header-section	HTML 的 HEAD 区域。可以使用此区域添加附加的样式定义等。
preliminary-section	“预发布”警告区域。仅当注释文档中使用 <preliminary> 标记显式标出，或通过文档引擎的 Preliminary 配置为 true 时，才会显示该区域。
summary-section	<summary> 标记对应的区域。tag.
thread-safety-section	“线程安全”区域。
syntax-section	“语法”区域。
value-section	<value> 标记对应的“属性值”区域。
parameter-section	<param> 标记对应的“参数”区域。
returnvalue-section	<returns> 标记对应的“返回值”区域。
implements-section	“接口实现”区域。
remarks-section	<remarks> 标记对应的“备注”区域。
after-remarks-section	“备注”区域后的区域。 注意: 不管“备注”区域是否存在，此区域总是存在的。
obsolete-section	“已过时”区域。
events-section	<event> 标记对应的“事件”区域。
exceptions-section	<exception> 标记对应的“异常”区域。
example-section <example>	标记对应的“示例”区域。
member-requirements-section	(某一个成员的)“要求”区域。
type-requirements-section	(类型的)“要求”区域。
seealso-section	“请参见”区域。
enumeration-members-section	“枚举成员”区域。
footer-row	页脚区域。
title-row	页眉区域。
overloads-remarks-section	重载页面的“备注”区域。
overloads-example-section	重载页面的“示例”区域。
overloads-summary-section	重载页面的“摘要”区域。
xml-data-island	HTML部嵌入的 XML 数据区域，可以附加自定义的元素或内容。 仅对 VS.NET 2003 文档引擎有效。

实现一个新的文档引擎
　实现一个新的文档引擎至少需要编写两个类:

一个从 NDoc.Core.DocumenterBase 继承而来的类

一个从 NDoc.Core.DocumenterConfigBase 继承而来的类

DocumenterConfigBase 是用于存储文档引擎配置信息的基类。它已经包含了一些通用的配置项，这些通用配置主要用于配置 NDoc 中间 XML 数据文件的生成动作。您编写的子类可以添加所需要的特定配置项(比如生成的文档保存在什么路径下等)。

DocumenterBase 是文档引擎的基类。文档引擎的工作模式是，第一步生成 NDoc 中间 XML 数据文件，第二步由各文档引擎将中间 XML 数据文件、分别转换成所需的最终文档格式。此基类完成了第一步的工作，您编写的子类只需完成第二个步骤。

必须实现的成员包括 Clear, Build 方法以及 MainOutputFile 属性等抽象(abstract)成员。

实现 Build 方法时, 可以调用基类的 MergeXML 方法，它完成第一步的 NDoc 中间 XML 数据文件的合并和制作。

使用 XML 文档引擎 可以导出一个 NDoc 中间 XML 数据文件的样例。您可以通过分析它，调试您的自定义转换代码或 XSLT 转换定义。使用 UseNDocXmlFile 配置项，可以节省您的调试时间。

文档引擎是如何加载的
　NDoc 通过反射发出(Reflection)机制动态分析和加载文档引擎。NDoc 启动时，自动检查程序(NDocGui.exe 或 NDocConsole.exe)所在路径中、所有以如下格式命名的程序集:

NDoc.Documenter.<NAME>.dll

其中 <NAME> 是文档引擎的名称(注: 可能与界面中显示的名称不同)。

NDoc 从这些程序集中分析、尝试查找 DocumenterBase 的子类，并加载找到的文档引擎。

为 NDoc 贡献代码
您可以有很多种选择，为 NDoc 的开发做出有益的贡献。

• 加入 ndoc-users 邮件列表 是最简单的方式、和其他用户分享您的使用心得体会和经验。
• 如果您发现了 bug，或者有一些不错的新功能建议，请使用 NDoc tracker database， 让我们了解您的发现和想法。
• 如果您有更多空闲的时间，希望成为 NDoc 开发组的成员、和我们一起实现那些 new features 或者修复那些已知的 bugs，请通过NDoc SourceForge 站点联络项目的负责人、管理员，我们会帮助您开始工作。我们欢迎越来越多的人们加入 NDoc 队伍！
• 感谢您使用 NDoc！

NDoc 用户邮件列表
　您也可以搜索 ndoc-users 邮件列表的存档邮件，或者发送问题到这个邮件列表。

NDoc 跟踪数据库
　如果通过以上途径还是没有找到您要的答案，您可以尝试 NDoc 在 SourceForge.net 维护的 Tracker database。

• 提交一个支持请求(support request)
• 提交 Bug 报告
• 提交新功能建议

介绍 NDoc 的文章
　网络中还有很多不错的 NDoc 介绍文章，下面有些文章发布时间很早，有些链接已经失效了。

• [Documenting C# with XML comments], 作者 Ollie Cornes
• [Using NDoc: Adding World-Class Documentation to Your .NET Components], 作者 Shawn Van Ness
• [Fixing NDoc to emit links for Everett's MSDN docs], 作者 Shawn Van Ness
• [Integrate NDoc HTML Help 2 in Visual Studio.NET], 作者 Fons Sonnemans
• [Creating class documentation with NDoc], 作者 Rick Harris
• [Integrating Help into Visual Studio.NET], 作者 Sune Trudslev