在 Eclipse Help 中如何组织 Java API 参考文档

本文介绍了生成易用且可供搜索的 Java 应用程序编程接口（Java application programming interfaces，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_src/DITA-OT1.2-src/src 目录中找到本文实例中使用的源代码。

关于 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.0Bundle-ManifestVersion: 2Bundle-Name: Doc Plug-inBundle-SymbolicName: org.dita.dost.doc; singleton:=true Bundle-Version: 1.0.0Bundle-Activator: org.dita.dost.doc.DocPluginBundle-Localization: pluginRequire-Bundle: org.eclipse.ui, org.eclipse.core.runtimeEclipse-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 outputPlugin.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 选项卡导航

要生成包注释文件，您必须将其命名为 package.html，并且放在源代码树中的包目录下，和 .java 文件在一起。Javadoc 将自动寻找该位置中的此文件名。注意该文件名等同于所有包。

包注释文件的内容是用 HTML 写的大文档注释，像其他所有注释一样，有一个 例外：
文档注释中不应该包含注释分隔符 /** 或 */ 或主要的星号。在书写注释时，您应该在第一句中写上该包的摘要，而不是写上标题或其他文本。
您可以包含包标签，如同所有文档注释一样，所有的标签，除了 {@link} ，都必须出现在描述之后。如果您在包注释文件中添加 @see 标签，那么它必须有全限定名。

SUN Javadoc 将生成源自四种不同类型的“源”文件的输出：
类的 Java 语言源文件（.java）、包注释文件、概要注释文件，和各式各样未处理的文件。

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="doc/overview-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>

 

 

 

编辑或向源代码文件添加完新的 API 文档之后，您应该生成文档来确保结果是您所预期的。

在 Eclipse 3.2 中，可以将全部的 doc 插件作为单个的 jar 文件进行加载，它包含要进入 doc.zip 文件的所有文件，以及通常的插件文件：manifest.mf、plug-in.xml、plug-in.properties，等等。在 Eclipse 3.2 之前，所生成的 Javadoc 文件和静态的 HTML 文件，以及扩展点 schema HTML 文件都会放在 doc.zip 文件中。

未编制文档的代码很难或不可能让人理解，不可用，并且难以管理。JavaToc doclet 是有价值的工具。我真的希望本文将帮助您找到在您的项目中使用 JavaToc doclet 的兴趣。

注意

“Simplicity is the soul of efficiency”。 —— Austin Freeman

“我们生活在当今规范的时代。每个知识领域中可用的信息量如此巨大，以至于为了理解并使用它们，人们必须成为专家。随着可用的材料知识越来越多，就需要更多样化的研究和更多的专家。”

 

 

此文档中提供的信息没有受到任何正式的 IBM 测试，并且“AS IS（按原样）”分布，在表示或暗示中都没有任何类型的担保。
本文档中介绍的信息的使用或者这些技术的实现是读者的责任，并且依赖于读者评价并集成到它们的操作环境中的能力。

结束语

后面的文章，Eclipse Java API reference structure generated with JavaTOC doclet 将介绍利用 JavaTOC doclet 和 Eclipse Plug-in Help 系统自动生成可供搜索的 Java API 参考文档（TOC 导航）的过程。在本系列即将发表的文章中，我们还将更深入地研究 API 文档编写和生成技术，以及一些来自 IBM 的增值的提高，包括 Java DITA API 规范和如何使用它。

下载

描述 名字 大小 下载方法 Example of API reference without toc navigation org.dita.dost.user.zip 381KB HTTP Example of API reference with toc navigation org.dita.dost.zip 364KB HTTP 关于下载方法的信息

参考资料

学习

• 您可以参阅本文在 developerWorks 全球网站上的 英文原文。
  
  
• 参见 Javadoc 主页，了解更多关于 Sun Microsystems Javadoc 工具的信息。
  
  
• 浏览 Doclet.com，Javadoc 工具的 Doclet 扩展的存储库。
  
  
• Sun 的教程 “How to Write Doc Comments for the Javadoc Tool” 介绍了 Javadoc 的规则和基本原理。
  
  
• Java 语言通过 Javadoc 注释约定集成了 API 文档。阅读 David Gallardo 的文章， “Java 理论和实践: 我必须对那些内容进行文档编制吗？” ，了解如何利用 Plug-in Development Environment 的代码生成向导创建 Eclipse 插件。
  
  
• 参见来自 IBM developerWorks 的“使用 Eclipse 帮助系统为项目编制文”。
  
  
• 对 Eclipse 感兴趣的人都会找到该学习指导，Eclipse Learning Guide，里面都是有帮助的技巧和有用的链接。
  
  
• 文章 “集中化 Eclipse 中的帮助功能” 说明如何利用 Eclipse 的帮助及插件架构的动态特性来令您生成统一的帮助存储库。它着重于如何用内容的帮助表来创建 Eclipse 插件，如何使用 Infocenter 来具体化帮助文件，以及如何创建允许您由 Eclipse 的主菜单访问统一的帮助存储库的新菜单项。
  
  
• 开发人员有时候需要访问帮助系统，而有时候您希望远程的访问。
  在文章 “Running the WebSphere Studio help system remotely” 中，Angel Vera 向您展示了如何运行 WebSphere Studio Application Developer 帮助系统。
  
  

获得产品和技术

• 出自 IBM alphaWorks 的 Documentation Enhancer for Java 是通过增加由静态地分析相应的 Java 类文件所收集的新的信息（语义信息、分类，和可浏览性）来增强 Javadoc 文件的工具。
  
  
• 在 eclipse 工程下载 页面上下载 Eclipse Platform Plug-in SDK。
  
  
• 加入 Eclipse Platform 社区，并在 eclipse.org 下载 Platform。在 eclipse.org 上，您还可以找到 Eclipse 工程的术语和描述词汇表，以及技术文章和新闻组。Eclipse Platform 白皮书详细说明了 Eclipse 的主要组件和功能。
  
  
• 在 developerWorks 中国网站 XML 专区上寻找更多 XML 资源。
  
  

讨论

• 在我的“API 文档过程系列文章”中的
  • “Creating Javadoc API documentation with directly updated source”
  • “Creating Javadoc API documentation with indirectly updated source”
  中寻找更多关于开发人员与文档工程师之间的协作的信息。