NDoc 文档引擎

概述

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

NDoc 的设计具有很强的可扩展性，您可以自己创作输出特定格式文档的、新的文档引擎。

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

将从程序集中通过反射发出读取的类型/成员信息，和 /doc XML 文档中的注释文档，合并在一起，即 NDoc 中间 XML 数据文件。
通过 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> 属性值文档时，是否输出红色的提示文本。

输出过滤

DocumentEmptyNamespaces

是否输出空的命名空间。(默认为否)

DocumentExplicitInterfaceImplementations

是否输出显式实现的接口成员。(默认为否)

DocumentInheritedFrameworkMembers

是否输出从 .NET Framework 中的类、结构等继承下来的成员。(默认为输出)

注意: 如果 DocumentInheritedMembers 为 None, 此配置被忽略。

DocumentInheritedMembers

如何输出继承的成员：可选择不输出、只输出继承的实例成员或者是全部继承成员都输出。

它有三个选项:

None	不输出继承的成员。
Instance	只输出继承的实例成员。(默认选项)
InstanceAndStatic	输出全部继承的实例和静态成员。

DocumentInternals

是否输出 internal (VB.NET 中为 Friend) 的类型或成员。(默认为否)

DocumentPrivates

是否输出 private (VB.NET 中为 Private) 的类型或成员。(默认为否)

有时需要为公司内部创建文档时，或许有用。

DocumentProtected

是否输出 protected (VB.NET 中为 Protected) 的成员。

因为对于非内部的受保护成员，在程序集外可以在继承的子类中访问，所以此项默认为输出。

DocumentProtectedInternalAsProtected

是否将 protected internal 成员视为 protected。(默认为否)

DocumentSealedProtected

是否输出密封类 (sealed, VB.NET 中为 NotInheritable) 的 protected 成员。(默认为否)

注意: 如果 DocumentProtected 为 false，则忽略此项配置。

EditorBrowsableFilter

一个过滤器，根据类型或成员的 EditorBrowsable 属性(attribute)值，过滤在编辑器(如 VS.NET 的智能感知功能)中不可见的类型或成员。

警告：开启此过滤器，可能导致最终文档中出现死链接，任何指向被过滤掉的类型或成员的链接都将无效。

可选项:

Off	关闭此过滤器。(默认选项)
HideNever	过滤掉该属性可浏览状态为 EditorBrowsableState.Never 的类型或成员。
HideAdvanced	过滤掉该属性可浏览状态为 EditorBrowsableState.Never 或 EditorBrowsableState.Advanced 的类型或成员。

注意: 在 NDoc 1.3 中，请优先考虑在代码注释中使用 <exclude/> 标记屏蔽对某些类型或成员的输出。

SkipNamespacesWithoutSummaries

是否跳过缺少概述信息的命名空间。(默认为否)

线程安全的输出

IncludeDefaultThreadSafety

是否为没有显式 <threadsafety> 文档的类型、添加默认的线程安全文档。注意：默认的线程安全文档，将根据 StaticMembersDefaultToSafe 和 InstanceMembersDefaultToSafe 的配置产生。

StaticMembersDefaultToSafe

指示文档引擎将类型的静态成员视为线程安全的。若 IncludeDefaultThreadSafety = false，此配置被忽略。

InstanceMembersDefaultToSafe

指示文档引擎将类型的实例成员视为线程安全的。若 IncludeDefaultThreadSafety = false，此配置被忽略。