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 属性。”