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 支持的标记
  • 标记用法
• 定义您自己的标记
  • 可用 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 文档标记
新标记

标记
说明

Directs NDoc to exclude the tagged type or member from the documentation.
The tag overrides all visibility options.

Marks the documentation of a type or member as preliminary.
This tag can include text and block tags like 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.

增强的标记

标记
说明

• "lang" attribute
• No more to prevent indent
• "Escaped" attribute

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 会用新的配置项改写。

改进的超链接逻辑
将形成一个指向另一个类型/成员的文档的链接。在 NDoc 1.3 中，如果一个 HTML 页中出现了多个指向同一个类型/成员的文档的 ，则只转换第一个为超链接，其余的不表示为超链接、只显示为粗体。这将使页面不至于太杂乱。

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 注释越多，最终生成的代码文档越专业。程序集的使用者越能从中获得帮助。

一般而言的最低要求，对于每一个公共类型，应该给它的所有公共的和受保护的成员添加

注释，以描述该成员表示什么意义或者会做些什么动作。

在 VS.NET 中，C# 代码编辑器，提供了一些自动完成的功能，帮助我们创建基本的 XML 注释。

比如如下的代码:

public class MyClass() {
public MyClass( string s ) { }
}

把光标移动到 MyClass 构造函数的上面一空行，敲 '/' 键三次，VS.NET 自动创建一个 summary XML 文档块:

public class MyClass() {
///

///
///

///
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 标记都被忽略。）

标记
说明

[NDoc 扩充]
对某个成员可能引发的事件的说明。

“示例”，帮助类库使用者理解类型/成员使用方法的示例代码。

对某个成员可以抛出的异常的说明。

[NDoc 扩充]

指示 NDoc 文档引擎将被标记的类型/成员排除在代码文档之外。
与文档引擎的“可见性”配置不符的，以 exclude 优先。

将代码文件外部的某 XML 文件中的一部分包含进代码文件来。

[NDoc 扩充]

为“重载列表”页面准备摘要、备注、示例等文档内容。只需在重载成员的第一个成员前面书写此区域即可。

标记有两种形式:

• 简单的形式，直接在 overload 中写文本，这些文本被处理为“重载列表”页面的摘要。没有备注、示例等区域。
• 复杂的形式，在 overload 内部，包含 summary, remarks, example 等标记分别表示“重载列表”页面的摘要、备注、示例等。
  示例:

///This method has two overloads.
///

This overload just says hello.

public void SayHello() { ... }
///

This one says hello to someone.

public void SayHello(string toSomeone) { ... }

成员的参数说明。

访问某成员所必需的 .NET Framework 安全性 CodeAccessPermission。

[NDoc 扩充]

将某类型/成员标记为“预发布”。内部的文本被当作警告文本用红色显示，可以包含 表示多行文本。如果缺少内部文本，则显示默认的警告文本: “[此文档为预发布版本，在未来版本中有可能改变。]”。

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

“备注”，对

的进一步注解。

“返回值”。

向页面的“请参见”区域添加一个链接。

请不要将此标记包含在 内部，它是一个顶级标记。

两种可选的语法:

• MSDN(CHS)
• DataSet

“摘要”，对类型/成员的摘要说明。

[NDoc 扩充]

“线程安全”，说明类型在多线程环境中是否安全。

NDoc 提供 static 和 instance 两个布尔的属性，可以自动生成像 .NET Framework SDK 类库文档中那样的标准文本。

threadsafety 标记内部可以包含额外的文本，会被显示到标准文本的下方，说明额外的信息。例如:

///

The summary description for SafeClass.

///
/// More information about using this class across thread
///
public class SafeClass() { ... }

“属性值”。

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

标记
说明


多行的代码块。

一个列表或表格。

[NDoc 扩充]

“注意”块。

例如:

///

/// This is a note in the summary.
///

public class SomeClass() { ... }
将生成:

注意 This is a note in the summary.

表示一个段落。

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

标记
说明

将内部文本格式化为代码样式，用于表示行文中提到的短小代码片段。

加入指向方法参数的链接。

加入指向某个类型/成员或网络 URL 的链接。

两种可选的语法:

• MSDN(CHS)
• DataSet
• 
  其中 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 中，我们推荐您使用 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，短线和等号周围不要有空格。下面语法叙述中，中括号的部分是可选的。路径中如果包含有空格，则需要用引号(")括起来。