org.eclipse.help.toc 的扩展点确定其为帮助系统的插件。
清单 1. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="1.0"?>
<plugin>
<extension point="org.eclipse.help.toc">
< toc file="doclet.toc.xml" primary="true"/>
</extension>
</plugin>
清单 2. MANIFEST.MF
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Doc Plug-in
Bundle-SymbolicName: org.dita.dost.doc; singleton:=true
Bundle-Version: 1.0.0
Bundle-Activator: org.dita.dost.doc.DocPlugin
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
org.eclipse.core.runtime
Eclipse-AutoStart: true
清单 3. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="1.0"?>
<plugin
name = "%Plugin.name"
id = "org.dita.dost.user.doc"
version = "7.0.1.0"
provider-name = "%Plugin.providerName">
<extension point="org.eclipse.help.toc">
< toc file="doclet.toc.xml" primary="true"/>
</extension>
</plugin>
将插件的名称、id、版本，和供应商名称改为适合您的工程的值。
清单 4. plugin.properties
# NLS_MESSAGEFORMAT_VAR
# ==============================================================================
# Online Help - Translation Instruction: section to be translated
# =============================================================================
Plugin.name = Building DITA output
Plugin.providerName = IBM
文件 doclet.toc.xml 指的是该插件的内容表，该文件将为 Eclipse 帮助窗口的左边窗格中的层次信息提供数据。一个简单的文件中包含如清单 2 所示的内容。
清单 5. doclet.toc.xml
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Building DITA output">
<topic label="API References" href="index.html"/>
</toc>
本文内容包括：
Java API 参考文档结构
构建易用且可供搜索的 Java API 文档
深思熟虑的方法
关于 Javadoc 和 JavaTOC doclet
用标准的 Javadoc 工具生成的 Eclipse Javadoc API 参考结构
标准的 Javadoc 导航栏组织
用 JavaTOC doclet 生成的 Eclipse Javadoc API 参考结构
Eclipse Java API 参考结构和 TOC 生成必要文件
注意
结束语
下载
参考资料
本文介绍了生成易用且可供搜索的 Java 应用程序编程接口（Java application programming interfaces，API）的参考文档的不同方法。
本系列的 第 2 部分，描述了生成便于使用和搜索的 Java 应用程序编程接口（API）参考文档的几种不同的方法。
背景
本材料假设您熟悉 Java 软件、Java API 参考文档结构、Javadoc 生成，并且想要了解更多关于如何提供改进的 Java API 参考文档的信息。
对于初学者，您应该了解下面这些内容：
Javadoc，Sun Microsystems 创建的开源工具。要了解更多信息，请阅读 java.sun.com/j2se/javadoc。
JavaHelp，拥有索引和搜索能力的帮助集。要了解更多信息，请参见 java.sun.com/products/javahelp。
Java Help 的编写工具。要了解更多信息，参考 java.sun.com/products/javahelp/industry.html 上的列表。
Standard Java Coding Conventions。要了解详细情况，请参见 java.sun.com/docs/codeconv 和快速参考单。
Javadoc Conventions。要了解详细情况，请参见 java.sun.com/j2se/javadoc/writingdoccomments。
构建易用且可供搜索的 Java API 文档
本文介绍了生成易用且可供搜索的 Java 应用程序编程接口（Java application programming interfaces，API）的参考文档的不同方法。所介绍的方法是用我开发的 JavaTOC doclet 生成的 Javadoc 标准解决方案和 Eclipse Plug-in Help System。JavaTOC doclet 生成内容表格（table-of-contents，TOC），使 Javadoc API 参考文档帮助用户很容易地在 API 参考文档中搜索具体类、接口，或方法。
Javadoc API 参考文档需要即是可浏览的，又是可供搜索的。标准的 Javadoc 没有完全提供此能力。充分编制文档的 API 可以满足许多目的，但是最重要的原因是令用户充分了解并搜索他们可用的 API 方法。如果没有适当的编制，或不可供搜索，那么即使是原始的作者可能也不理解源代码了。该解决方案就是要养成编制源代码文档的习惯，并且为 Java API 参考生成可供搜索的结构（TOC 导航）。JavaTOC doclet 通过为参考生成可供搜索的结构来解决此问题。
搜索和浏览假定信息是由特定查询的相关性拣选出来的，生成了许多特定的序列作为结果。举例来说，在标准的 Javadoc 中，对具体方法的描述的 API 信息的搜索返回整个类的描述。
深思熟虑的方法
生成 Java API 参考文档的工具相当多。我当前的推荐是结合 Javadoc 或 DITA API 规范使用的 JavaTOC doclet。
Javadoc 是 Sun 所有的，将开发人员的注释从 Java 源代码中抽取出来，并输出为 HTML 的工具。Javadoc 工具生成了 Java API 参考文档的基本结构。该结果是一组包和类的 Javadoc HTML API 文档。
JavaTOC doclet 生成了 TOC 导航，以及 Java API 参考文档的搜索能力。IBM DITA API 规范团队已经开发了一个 DITA 主题类型包，用于生成 Java API 文档文件以及将包含于 Eclipse Help 系统中的参考的导航清单。
以下的实例（没有 toc 导航的 API 参考的实例和具有 toc 导航的 API 参考的实例）使用了来自 DITA Open Toolkit 的 Java 源代码。DITA Open Toolkit 版本 1.0.2 或之上的版本提供了 Command Prompt 接口，作为几乎不了解 Ant 的用户轻松使用工具包的选择。当您下载完 zip 文件之后，您将会在 DITA-OT1.2_srcDITA-OT1.2-srcsrc 目录中找到本文实例中使用的源代码。
关于 Javadoc 和 JavaTOC doclet
标准的 Javadoc Help 和定制的 Eclipse Javadoc Help 的最大区别是是否提供 TOC 导航。标准的 Javadoc Help 提供一些额外的框，以让您浏览包和类。定制的 Eclipse Javadoc Help 包含 Eclipse 风格的 XML 导航文件，而不是那些额外的 HTML 框。 Eclipse 风格的 XML 导航文件生成了允许用户搜索具体包、类或接口的 TOC 导航。定制的 Eclipse Java API 参考解决方案提供了将要包含于 Eclipse 帮助系统中的文档的导航清单。
整个 Eclipse 平台都是围绕插件的思想开发的。如果您想向 Eclipse 平台中加入您的帮助文档，那么您必须开发新的帮助插件。插件由 HTML 和图像文件、XML 格式的内容文件的表格，以及清单文件。JavaTOC doclet 自动生成整个 Eclipse 插件结构，包括直接从 Java 源代码中抽取的 XML 导航 TOC 文件。
JavaTOC doclet 是与 Javadoc 工具一起工作的定制程序。该 doclet 提供了允许您在 Javadoc 文档文件之上生成 TOC 导航的不断增加的灵活性。
JavaTOC doclet 为 IBM DITA API 规范（开发它是用于为了编制及生成 Java API 参考而生成 Java DITA（XML）API 文件）集成了 DITAdoclet 工具。该解决方案还包括 Eclipse Help 系统中将包含的 Java API 参考文档的导航清单。
用标准的 Javadoc 工具生成的 Eclipse Javadoc API 参考结构
要在 Eclipse 中访问标准的 Javadoc 在线帮助，您可以在菜单栏上选择 Help > Help Contents。它将在自己的浏览器中打开在线帮助。
在左窗格中，有内容表格、搜索，和上下文敏感的帮助链接的选项卡视图。下面的实例，图 1，显示了标准的 Javadoc API 参考结构。它是仅仅用标准的 Javadoc 工具在 Eclipse 环境中生成的。
图 1. Javadoc API 参考结构
org.eclipse.help.toc 的扩展点确定其为帮助系统的插件。
清单 1. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="1.0"?>
<plugin>
<extension point="org.eclipse.help.toc">
< toc file="doclet.toc.xml" primary="true"/>
</extension>
</plugin>
清单 2. MANIFEST.MF
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Doc Plug-in
Bundle-SymbolicName: org.dita.dost.doc; singleton:=true
Bundle-Version: 1.0.0
Bundle-Activator: org.dita.dost.doc.DocPlugin
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
org.eclipse.core.runtime
Eclipse-AutoStart: true
或者
清单 3. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="1.0"?>
<plugin
name = "%Plugin.name"
id = "org.dita.dost.user.doc"
version = "7.0.1.0"
provider-name = "%Plugin.providerName">
<extension point="org.eclipse.help.toc">
< toc file="doclet.toc.xml" primary="true"/>
</extension>
</plugin>
将插件的名称、id、版本，和供应商名称改为适合您的工程的值。
清单 4. plugin.properties
# NLS_MESSAGEFORMAT_VAR
# ==============================================================================
# Online Help - Translation Instruction: section to be translated
# =============================================================================
Plugin.name = Building DITA output
Plugin.providerName = IBM
文件 doclet.toc.xml 指的是该插件的内容表，该文件将为 Eclipse 帮助窗口的左边窗格中的层次信息提供数据。一个简单的文件中包含如清单 2 所示的内容。
清单 5. doclet.toc.xml
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Building DITA output">
<topic label="API References" href="index.html"/>
</toc>
href = "index.html" 是所生成的 javadoc api 参考的链接。如果您想要让右边的窗格在打开文档时不带有 HTML 框，那么该链接为 href="overview-summary.html"。
标准的 Javadoc 导航栏组织
标准的 Javadoc 导航栏不允许用户搜索具体的包、类，或方法。
这是 SUN Javadoc 组织并描述 Javadoc 选项卡导航的方式 —— 图 2。
图 2. Javadoc 选项卡导航
Overview
Overview 页是此 API 文档的第一页，并且列出所有包，并带有摘要。该页还可以包含一组包的全面的描述。OBSERVATIONS：
不要忘记在名为 Overview.html 的文件中写上包级 Javadoc。该文件应该放在代码文件所在的根目录下。Javadoc 能够挑出该文件并且使用其内容
。
Package
每个包都有一个包含它的类和接口，以及对应摘要的列表的页面。该页包含五类：Interfaces、Classes、Exceptions、Errors，和 Constants。
OBSERVATIONS：
不要忘记在名为 package.html 的文件中写上包级 Javadoc。该文件应该放在这个包的代码文件所在的目录下。Javadoc 能够挑出该文件并且使用其内容
。
Class/Interface
每个类、接口、内隐类和内隐接口都有其自己单独的页面。这些页面都有三个部分，包括类/接口描述、摘要表，和详细的成员描述：
每个摘要项都包含来自该项的详细描述的第一句话。
摘要项是按字母顺序的，而详细的描述是按照它们出现在源代码中的顺序排的。这保留了程序设计人员建立的逻辑分组。
Use
每个编制了文档的包、类和接口都拥有它自己的 Use 页。该页介绍了什么包、类、方法、构造方法和域使用了已知类或包的任意部分。
Tree (Class Hierarchy)
对于所有包有一个 Tree（Class Hierarchy）页，并且每个包有一个层次。每个层次页包含一列类和一列接口。
Deprecated
Deprecated API 页面列出了全部遭到反对的 API。遭到反对的 API 是不被推荐使用的，一般是由于改进了，并且替换的 API 通常是已知的。遭到反对的 API 可能在将来的实现中被去掉。
Index
Index 包含了所有类、接口、构造函数、方法，和域的字母表。
Prev/Next
这些链接将您带到下一个或前一个类、接口、包，或相关的页。
Frames/No Frames
这些链接显示并隐藏 HTML 框。所有的页都有框或者没有框。
用 JavaTOC doclet 生成的 Eclipse Javadoc API 参考结构
结构化的信息方法，例如那些用 XML 写的，使用 Eclipse JavaTOC doclet 和 Javadoc Help 风格，满足了可浏览的和可供搜索的 Java API 参考文档需求。
要使用 Eclipse 帮助插件中的导航，Information Developer（信息开发人员）必须提供 XML 文档格式的内容表（table-of-contents，TOC）。文档左边是可折叠的索引，右边是 HTML 文档。HTML 文件可以用 Javadoc 或 IBM DITA Java API 规范生成。
您可以手动生成 TOC，或者使用 JavaTOC doclet 自动生成。JavaTOC doclet 为您生成了罗列出包和所包含的类和接口的 Java API 参考 TOC 结构。
要生成 API 参考 HTML 文件，您可以运行 Javadoc 工具或使用 IBM DITA API 规范解决方案来编写并生成 Java API 参考 HTML 文件 —— 图 3。
图 3. HTML—Kit 编辑器
如果您使用 JavaTOC doclet，那么 API 参考文档既是可浏览的，又是可供搜索的。搜索能力是可能的，因为使用了结构化的信息方法（XML）。
使用 XML 生成 API 参考文档的结构的一个积极效果是内容将自动索引用于搜索，如果您使用标准的 Javadoc 解决方案来生成内容，那么内容将不会默认索引用于搜索。
Eclipse Java API 参考结构和 TOC 生成必要文件
下面的清单提供了用于生成上面 Java API 参考 TOC 导航结构的 TOC XML 文件的实例。可以手动或利用 JavaTOC doclet 自动生成该文件。参见下面的下载部分，下载 Eclipse 的 Java API 参考 XML TOC 实例。
下面的清单展示了参考一个 TOC XML 文件的 Eclipse Java API 参考插件的实例。
清单 6. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="1.0"?>
<plugin>
<extension point="org.eclipse.help.toc">
<toc file="doclet.toc.xml" primary="true"/>
</extension>
</plugin>
下面的清单展示了根据 Java 包结构参考一个以上 TOC XML 文件的 Eclipse Java API 参考插件的实例。当查看该文档时，使用一个 TOC 或多个 TOC XML 文件的方法之间没有什么差别。
清单 7. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="1.0"?>
<plugin
name = "%Plugin.name"
id = "org.dita.dost.user.doc"
version = "7.0.1.0"
provider-name = "%Plugin.providerName">
<extension point="org.eclipse.help.toc">
<toc file="doclet.toc.xml" primary="true"/>
<toc file="org.dita.dost.exception.toc.xml"/>
<toc file="org.dita.dost.index.toc.xml"/>
<toc file="org.dita.dost.invoker.toc.xml"/>
<toc file="org.dita.dost.log.toc.xml"/>
<toc file="org.dita.dost.module.toc.xml"/>
<toc file="org.dita.dost.pipeline.toc.xml"/>
<toc file="org.dita.dost.platform.toc.xml"/>
<toc file="org.dita.dost.reader.toc.xml"/>
<toc file="org.dita.dost.util.toc.xml"/>
<toc file="org.dita.dost.writer.toc.xml"/>
</extension>
</plugin>
您可以使用 navref 和 anchor 元素，以及图元素的 anchorref 属性来生成 Eclipse 输出中的集成点，在这些地方接入导航文件，或在运行时附到其本身上。参见 Eclipse 参考资料，了解更多关于编写 Eclipse 导航文件的信息。
清单 8. doclet.toc.xml
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="Building DITA output">
<topic label="Overview" href="docoverview-summary.html">
<link toc="org.dita.dost.exception.toc.xml"/>
<link toc="org.dita.dost.index.toc.xml"/>
<link toc="org.dita.dost.invoker.toc.xml"/>
<link toc="org.dita.dost.log.toc.xml"/>
<link toc="org.dita.dost.module.toc.xml"/>
<link toc="org.dita.dost.pipeline.toc.xml"/>
<link toc="org.dita.dost.platform.toc.xml"/>
<link toc="org.dita.dost.reader.toc.xml"/>
<link toc="org.dita.dost.util.toc.xml"/>
<link toc="org.dita.dost.writer.toc.xml"/>
</topic>
</toc>
主要的内容的 XML 表必须有一个标题（Eclipse 中的标签），为了加载帮助的内容表。
文件 org.dita.dost.index.toc.xml 是另一个内容表，并且应该与任何其他 toc.xml 文件的格式一样。
清单 9. org.dita.dost.index.toc.xml
<?xml version="1.0" encoding="UTF-8"?>
<?NLS TYPE="org.eclipse.help.toc"?>
<toc label="org.dita.dost.index Package" link_to="../doclet.toc.xml#java.packages">
<topic label="org.dita.dost.index Package"
href="doc/org/dita/dost/index/package-overview.html">
<anchor id="org.dita.dost.index.packages"/>
<topic label="IndexTerm" href="doc/org/dita/dost/index/IndexTerm.html"/>
topic label="IndexTermCollection"
href="doc/org/dita/dost/index/IndexTermCollection.html"/>
<topic label="IndexTermTarget" href="doc/org/dita/dost/index/IndexTermTarget.html"/>
<topic label="TopicrefElement" href="doc/org/dita/dost/index/TopicrefElement.html"/>
</topic>
</toc>
