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,短线和等号周围不要有空格。下面语法叙述中,中括号的部分是可选的。路径中如果包含有空格,则需要用引号(")括起来。

你可能感兴趣的:(B0.▲,C#)