[转]使用 JavaTOC doclet 生成的 Eclipse Javadoc API 参考结构
Java API 参考文档, 第 2 部分
使用 JavaTOC doclet 生成的 Eclipse Javadoc API 参考结构
本文是系列文章的第 2 部分，描述了生成便于使用和搜索的 Java 应用程序编程接口（API）参考文档的几种不同的方法。
- Quick Review
- 通过 JavaTOC doclet 生成的 Eclipse Javadoc API 参考文档结构
- Using the JavaTOC doclet to create one XML TOC file.
- Using the JavaTOC doclet to create multiple XML TOC files.
- Packaging the plug-in
- 查看您的文档
- 注意
- 小结
- 下载
快速回顾
在系列文章的第 1 部分“Java API 参考文档, 在 Eclipse Help 中如何组织 Java API 参考文档”中，我介绍了一种生成便于使用和搜索的 Java 应用程序编程接口（API）参考文档的方法。
本文将讨论 JavaTOC doclet 工具，以及如何使用和扩展它。这种方法采用 Javadoc 标准解决方案和我所开发的 JavaTOC doclet 所生成的 Eclipse Plug-in Help System。JavaTOC doclet 工具生成了 Eclipse 帮助系统所必需的 XML 内容目录（TOC）导航文件，以及 HTML 格式的 Sun Javadoc API 参考文档。为了更好的理解这种方法，我通过一个演示系统举例如何使用 Sun Javadoc 和 JavaTOC doclet 工具（使用命令行提示）。
通过 JavaTOC doclet 生成的 Eclipse Javadoc API 参考文档结构
设计的约束条件
您能够通过运行 JavaTOC doclet 和 Javadoc 来生成 Java API 参考文档、内容目录（TOC）导航和插件程序结构。或者，您只需运行 JavaTOC doclet 就能够从现已存在的文档中生成 TOC 导航。
工作流程
对于每一个您希望贡献给 Eclipse 帮助系统（Java API 参考小节）的插件程序来说，通常地，按照以下工作流程被处理：
- 运行 JavaTOC doclet 为 Eclipse 帮助系统创建所有必需的插件程序文件（plugin.xml、primary.plugin.toc.xml、META-INF/MANIFEST.MF、build.properties 和 plugin.properties）。
plugin.xml 文件扩展了 org.eclipse.help.toc 扩展点，需要指明：- 一个 XML TOC 文件，如果您仅仅拥有两个 Java 包的话。
- 多个 XML TOC 文件，当您拥有多个 Java 包的话。
- 在您的 Java 源代码文件上运行 Javadoc （Sun Microsystems Inc.），为 Java API 参考文档创建 HTML 文件。
- 测试生成的 Java API 参考文档。
Ant 是目前看来人人都在使用的 Java 建造系统。如果您还没有使用过 Ant 的话，请登录 Jakarta 网站，或者“Open Source Java: Ant”。
我最喜欢的运行 JavaTOC doclet 工具的方式就是通过 Ant 建造系统来进行的，但是在本文中，我将向您展示如何从命令提示行中使用 JavaTOC doclet。
通过命令行建造 XML TOC 文件输出
JavaTOC Doclet Toolkit 1.0.0 版本为不熟悉 Ant 的用户提供了一个命令行接口，以方便他们使用这一工具集。
- 请确保 Javadoc 被安装在您的路径下。（...\jdk1.5.0_06\bin\javadoc.exe）
- 请注意：典型情况下，Javadoc 将拥有一个类似于 C:\Program Files\Java\jdk1.5.0_06\bin 的 路径。
- 下载 JavaToc Doclet ZIP 文件并且将其解压缩到您所选择的文件夹下（例如：C:\doclet\on Windows）。它将创建一个 JavaTOC 目录，其中包括 bin\、demo\ 和 doc\subdirectory，其中：
- bin 文件夹包含 Java 类，您需要运行 doc 扩展作为 jar 库（DocletTOC.jar）。
- doc 文件夹包含 JavaTOC 用户指南和 org.dita.dost.doc HTML 格式的插件程序 API 文档（一个例子）。
- src 资源库包含您能够用作例子的 Java 源文件。
（您能够直接从 SOURCEFORGE 网站上面下载源文件 DITA-OT1.3_src.zip ）。
- 使用 @packages 选项将包的完整类型名称放置到一个单独的文件之中。
- 从 c:\doclet> 目录下运行下列命令：javadoc @tocdoclet @options @packages （列表 1 至列表 3）。
列表 1. tocdoclet
-doclet com.ibm.malup.doclet.config.TOCDoclet
-docletpath C:\doclet\bin\TOCNavDoclet.jar
列表 2. 选项
-sourcepath src
-d com.ibm.doc_plugin_name
-overview src/overview-summary.html
-doctitle 'Navigation label'
-version 'plugin_version' -pluginid plugin_id
-provider 'plugin_provider_name'
-anchor 'plugin_name'
列表 3. 包
com.ibm.package1
com.ibm.package2
...
com.ibm.packageN
列表 4. 移除文件
source\..\..\package1\fileA.java,source\..\..\package2\fileB.java, , ,
source\..\..\packageN\fileN.java
- 您能够通过 NotePad 编辑器对这个文件进行修改。
- JavaTOC doclet 将插件程序的名称、标号、版本以及提供者名称的值传递到您的 Eclipse 插件程序项目，如列表 2 所示。
来自 org.eclipse.help.toc 插件程序的扩展点将其识别为一个能够帮助系统的插件程序。
文件 doclet.toc.xml 被引用为这一插件程序的内容目录；这个文件将为 Eclipse 帮助窗口的左侧面板中的分等级的信息提供数据。 - 包文件包含类似列表 3 中所显示内容。
- JavaTOC doclet 将插件程序的名称、标号、版本以及提供者名称的值传递到您的 Eclipse 插件程序项目，如列表 2 所示。
- 运行命令：javadoc @tocdoclet @options @packages @removefiles —— 移除所有您所不希望被显示的类（列表 4）。
JavaTOC doclet 所提供的被支持的参数的列表：
| 参数 | 描述 |
|---|---|
| -d <目标文件夹> | 指明生成文档的目标文件夹。默认情况下，即是当前的目录。 |
| -doclet <类> | 通过改变 doclet 生成输出。 要运行 doclet，您将需要在 Javadoc 命令行上使用选项：-doclet <class> 指定 doclet 类。 |
| -sourcepath <路径列表> | 指明源文件的位置。 默认情况下，src 即是当前文件夹。 |
| -docletpath <路径> | 指明 doclet 类文件的位置。 |
| -doctitle <html 代码> |  包括 Eclipse 插件程序的标题。这在 manifest.mf 文件中被反映出来： Plugin.name = Building MDA RXE |
| -overview <文件> | 指明查找概述文档的位置（HTML 文件）。 |
| —version <插件程序版本> | 指明插件程序的版本号的细节。 |
| —provider <插件程序提供者> | 指明插件程序提供者名称的细节。 |
| -anchor | 链接通过使用完整的参考内容目录被指明，例如： <toc link_to="../the_other_plugin_id/path/to/toc.xml#anchor_id"/>  |
| -notree |
org.eclipse.help.toc 贡献指明了一个或者多个被关联的 XML 文件，这些文件包含了您的帮助的结构以及它们与其他插件程序所贡献的帮助的综合。 如果您要为一个完整尺寸的项目生成文档的话，那么请指定创建多个 XML TOC 文件。请注意：错过这一标记参量将导致只能够创建一个 XML TOC 文件。 |
- doclet 为插件程序生成了输出 XML 文件，以及若干有用的文件，c:\doclet\com.ibm.doc_plugin_name 是您的插件程序的文件夹：
- plugin.xml
- plugin.properties
- .project
- META-INF\MANIFEST.MF
- com.ibm.packageN.toc.xml —— 用于在帮助浏览器中建造导航树的 TOC XML 文件
- buildJavaDoc.xml —— 用于从 Ant 环境中运行 JavaDoc 工具的 ANT 文件
- buildJavaDoc.bat —— 用于运行 JavaDoc 工具 BAT 的文件
- 从命令提示行（buildJavaDoc.bat）中运行 JavaDoc，为 API 文档创建 HTML 文件。
使用 JavaTOC doclet 创建一个 XML TOC 文件
至此，我们已经完成了对 doclet 的讨论，下面我们来看一个实际的例子，使用 JavaTOC doclet 和 DITA-OT 1.3 源文件（DITA-OT1.3_src.zip）。
一个 TOC 文件通过将被标记的标题映射到个体的 HTML 文件上，定义了进入 HTML 内容文件的关键入口，并且扮演一组 HTML 内容目录的角色。由于这个 TOC 文件描述了如何导航 HTML 内容，所以它们有时被作为导航文件使用。一个插件程序能够拥有一个或者多个 TOC 文件。
运行 org.dita.dost 实例
运行 bat 文件：C:\doclet\JavaTOC>TOCDoclet_dost.bat（列表 5 至列表 8）。
列表 5. TOCDoclet_dost.bat
javadoc @config @options @packages
列表 6. 配置
-doclet com.ibm.malup.doclet.config.TOCDoclet
-docletpath C:\doclet\bin\TOCNavDoclet.jar
列表 7. 选项
-sourcepath demo/src
-d demo/output/org.dita.dost.doc
-overview demo/src/overview-summary.html
-doctitle 'Building DITA output'
-pluginid org.dita.dost.doc
-provider XYZ
-version 1.0.1
列表 8. 包
org.dita.dost.index
org.dita.dost.invoker
org.dita.dost.log
org.dita.dost.module
org.dita.dost.pipeline
org.dita.dost.platform
org.dita.dost.reader
org.dita.dost.util
org.dita.dost.writer
org.dita.dost.exception
或者从命令提示行中 C:\doclet\JavaTOC> 目录下：
javadoc -doclet com.ibm.malup.doclet.config.TOCDoclet -docletpath C:\doclet\JavaTOC\bin\TOCNavDoclet.jar -sourcepath demo/src -d demo/output/org.dita.dost.doc -doctitle 'Building DITA output' -pluginid org.dita.dost.doc -provider XYZ -version 1.0.1 -overview demo/src/overview-summary.html org.dita.dost.index org.dita.dost.invoker org.dita.dost.log org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer org.dita.dost.exception
用于输出文件的目标文件夹
- doclet 为插件程序生成了输出 XML 文件，以及若干有用的文件，C:\doclet\JavaTOC\output\org.dita.dost.doc 是您的插件程序的文件夹（列表 9）：
- plugin.xml
- plugin.properties
- .project
- META-INF\MANIFEST.MF
- org.dita.dost.doc_toc.xml —— 用于在帮助浏览器中建造导航树的 TOC XML 文件
- buildJavaDoc.xml —— 用于从 Ant 环境中运行 JavaDoc 工具的 ANT 文件
- buildJavaDoc.bat —— 用于运行 JavaDoc 工具的 BAT 文件
列表 9. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?> <?eclipse version="3.0"?> <!-- ========================================================== --> <!-- This plug-in declares an online help --> <!-- contribution for IBM Rational Software Modeler. --> <!-- Licensed Materials - Property of IBM --> <!-- (c) Copyright IBM Corp. 2006. All Rights Reserved. --> <!-- ========================================================== --> <plugin name = "%Plugin.name" id = "org.dita.dost.doc" version = "7.0.1.0" provider-name = "%Plugin.providerName"> <extension point="org.eclipse.help.toc"> <toc file="org.dita.dost.doc_toc.xml" primary="true"/> </extension> </plugin>
插件程序的名称、标号、版本以及提供者的名称值等都是从 -d、-doctitle、—version 和 —provider 属性中自动生成的（列表 10）。
列表 10. plugin.properties
# NLS_MESSAGEFORMAT_VAR
# ==============================================================================
# Online Help - Translation Instruction: section to be translated
# =============================================================================
Plugin.name = Building DITA output
Plugin.providerName = IBM
插件程序名单文件通过将字符串置换为一个关键字而将它们的字符串具体化（例如 %pluginName），并且在 plugin.properties 文件中创建一个如下格式的入口：pluginName = "Online Help Sample Plugin"（列表 11）。
列表 11. META-INF\MANIFEST.MF
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Doc Plug-in
Bundle-SymbolicName: -pluginid; singleton:=true
Bundle-Version: 1.0.0
Bundle-Activator: -pluginid.DocPlugin
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
org.eclipse.core.runtime
Eclipse-AutoStart: true
org.eclipse.help.toc 插件程序的扩展点将其识别为一个帮助系统的插件程序。文件 doclet.toc.xml 被引用为这个插件程序的内容目录；这个文件将为 Eclipse 帮助窗口的左侧面板中的分等级的信息提供数据。
一个简单的文件包括类似列表 12 中所显示的内容。
列表 12. org.dita.dost.doc_toc.xml
<?xml version="1.0" encoding="UTF-8"?> <?NLS TYPE="org.eclipse.help.toc"?> <toc label="Building DITA output"> <topic label="Overview" href="overview-summary.html"> <topic label="org.dita.dost.index Package" href="../index/package-summary.html"> <topic label="IndexTerm" href="../index/IndexTerm.html"/> <topic label="IndexTermCollection" href="../index/IndexTermCollection.html"/> <topic label="IndexTermTarget" href="../index/IndexTermTarget.html"/> <topic label="TopicrefElement" href="../index/TopicrefElement.html"/> </topic> <topic label="org.dita.dost.invoker Package" href="../invoker/package-summary.html"> <topic label="AntInvoker" href="../invoker/AntInvoker.html"/> <topic label="CommandLineInvoker" href="../invoker/CommandLineInvoker.html"/> <topic label="JavaInvoker" href="../invoker/JavaInvoker.html"/> </topic> <topic label="org.dita.dost.log Package" href="../log/package-summary.html"> <topic label="DITAOTBuildLogger" href="../log/DITAOTBuildLogger.html"/> <topic label="DITAOTEchoTask" href="../log/DITAOTEchoTask.html"/> <topic label="DITAOTFailTask" href="../log/DITAOTFailTask.html"/> <topic label="DITAOTFileLogger" href="../log/DITAOTFileLogger.html"/> <topic label="DITAOTJavaLogger" href="../log/DITAOTJavaLogger.html"/> <topic label="LogConfigTask" href="../log/LogConfigTask.html"/> <topic label="MessageBean" href="../log/MessageBean.html"/> <topic label="MessageUtils" href="../log/MessageUtils.html"/> </topic> <topic label="org.dita.dost.module Package" href="../module/package-summary.html"> <topic label="Content" href="../module/Content.html"/> <topic label="AbstractPipelineModule" href="../module/AbstractPipelineModule.html"/> <topic label="ContentImpl" href="../module/ContentImpl.html"/> <topic label="DebugAndFilterModule" href="../module/DebugAndFilterModule.html"/> <topic label="GenMapAndTopicListModule" href="../module/MapAndTopicListModule.html"/> <topic label="IndexTermExtractModule" href="../module/IndexTermExtractModule.html"/> <topic label="ModuleFactory" href="../module/ModuleFactory.html"/> <topic label="MoveIndexModule" href="../module/MoveIndexModule.html"/> <topic label="MoveLinksModule" href="../module/MoveLinksModule.html"/> </topic> <topic label="org.dita.dost.pipeline Package" href="../pipeline/package-summary.html"> <topic label="AbstractPipelineInput" href="../pipeline/AbstractPipelineInput.html"/> <topic label="AbstractPipelineOutput" href="../pipeline/AbstractPipelineOutput.html"/> <topic label="AbstractFacade" href="../pipeline/AbstractFacade.html"/> <topic label="PipelineFacade" href="../pipeline/PipelineFacade.html"/> <topic label="PipelineHashIO" href="../pipeline/PipelineHashIO.html"/> </topic> <topic label="org.dita.dost.platform Package" href="../platform/package-summary.html"> <topic label="IAction" href="../platform/IAction.html"/> <topic label="DescParser" href="../platform/DescParser.html"/> <topic label="Features" href="../platform/Features.html"/> <topic label="FileGenerator" href="../platform/FileGenerator.html"/> <topic label="ImportAction" href="../platform/ImportAction.html"/> <topic label="InsertAction" href="../platform/InsertAction.html"/> <topic label="Integrator" href="../platform/Integrator.html"/> <topic label="IntegratorTask" href="../platform/IntegratorTask.html"/> </topic> <topic label="org.dita.dost.reader Package" href="../reader/package-summary.html"> <topic label="AbstractReader" href="../reader/AbstractReader.html"/> <topic label="AbstractXMLReader" href="../reader/AbstractXMLReader.html"/> <topic label="DitamapIndexTermReader" href="../reader/DitamapIndexTermReader.html"/> <topic label="DitaValReader" href="../reader/DitaValReader.html"/> <topic label="GenListModuleReader" href="../reader/GenListModuleReader.html"/> <topic label="IndexTermReader" href="../reader/IndexTermReader.html"/> <topic label="ListReader" href="../reader/ListReader.html"/> <topic label="MapIndexReader" href="../reader/MapIndexReader.html"/> </topic> <topic label="org.dita.dost.util Package" href="../util/package-summary.html"> <topic label="CatalogParser" href="../util/CatalogParser.html"/> <topic label="CatalogUtils" href="../util/CatalogUtils.html"/> <topic label="Constants" href="../util/Constants.html"/> <topic label="DITAOTCopy" href="../util/DITAOTCopy.html"/> <topic label="FileUtils" href="../util/FileUtils.html"/> <topic label="IsAbsolute" href="../util/IsAbsolute.html"/> <topic label="StringUtils" href="../util/StringUtils.html"/> </topic> <topic label="org.dita.dost.writer Package" href="../writer/package-summary.html"> <topic label="AbstractWriter" href="../writer/AbstractWriter.html"/> <topic label="AbstractXMLWriter" href="../writer/AbstractXMLWriter.html"/> <topic label="CHMIndexWriter" href="../writer/CHMIndexWriter.html"/> <topic label="DitaIndexWriter" href="../writer/DitaIndexWriter.html"/> <topic label="DitaLinksWriter" href="../writer/DitaLinksWriter.html"/> <topic label="DitaWriter" href="../writer/DitaWriter.html"/> <topic label="JavaHelpIndexWriter" href="../writer/JavaHelpIndexWriter.html"/> <topic label="PropertiesWriter" href="../writer/PropertiesWriter.html"/> </topic> </topic> </toc>
现在，我们已经拥有了所有的插件程序文件，它们已经为 Eclipse 帮助系统而被标记出来。您拥有用于 Java API 参考文档的结构，这些文档使得一个 Eclipse 中的导航能够通过一个被编写为 XML 文档的内容目录（TOC）帮助插件程序。这种可浏览的和可搜索的需要通过使用 XML 的这一结构化的信息方法被满足。
该文档的左侧是索引，右侧是 HTML 文档。
运行 JavaDoc 来创建 HTML 文件
从 C:\doclet\JavaTOC\demo\output\org.dita.dost.doc 目录下（buildJavaDoc.bat）的命令提示行中运行 JavaDoc 来为 API 参考文档创建 HTML 文件。
C:\doclet\JavaTOC\demo\output\org.dita.dost.doc>javadoc -sourcepath src -d doc -doctitle "Building DITA output" -overview src\overview.html org.dita.dost.index org.dita.dost.invoker org.dita.dost.log org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer org.dita.dost.exception
使用 JavaTOC doclet 来创建多个 XML TOC 文件
一个典型的 Java API 包括七个或者更多的包文件。通过 JavaTOC doclet，您仅仅能够维护一个文件（package.txt），其他的都是被生成的。您极大的缩短了开发时间，并且能够集中精力于为 API 记录文档，与此同时，JavaTOC 为您生成了 100% 的插件程序帮助代码。
运行同样的 org.dita.dost 实例
从 C:\doclet\ 目录中运行民命令提示行 JavaTOC doclet。C:\doclet\JavaTOC>javadoc @tocdoclet options.org.dita.dost @packages（列表 13）。
列表 13. options.org.dita.dost
-sourcepath demo/src
-d demo/output2/org.dita.dost.doc
-overview src/overview-summary.html
-provider XYZ -doctitle 'Building DITA output'
-notree
下面，我介绍 -notree 参数：
| 参数 | 描述 |
|---|---|
| -notree | 指明创建多个 XML TOC 文件。 请注意：错过这一参量将导致只能够创建一个 XML TOC 文件。 |
或者：
C:\doclet\JavaTOC>
javadoc -doclet com.ibm.malup.doclet.config.TOCDoclet -docletpath C:\doclet\JavaTOC\bin\TOCNavDoclet.jar -sourcepath demo/src -d demo/output/org.dita.dost.doc -doctitle 'Building DITA output' -pluginid org.dita.dost.doc -provider XYZ -version 1.0.1 -overview demo/src/overview-summary.html -notree org.dita.dost.index org.dita.dost.invoker org.dita.dost.log org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer
用于输出文件的目标文件夹（org.dita.dost.doc）
- doclet 为插件程序生成了输出 XML 文件，以及若干有用的文件，C:\doclet\JavaTOC\output\org.dita.dost.doc 是您的插件程序的文件夹：
- plugin.xml
- plugin.properties
- META-INF\MANIFEST.MF
- doclet.toc.xml
org.dita.dost.index.toc.xml，
org.dita.dost.invoker.toc.xml，
org.dita.dost.log.toc.xml，
org.dita.dost.module.toc.xml，
org.dita.dost.pipeline.toc.xml，
org.dita.dost.platform.toc.xml，
org.dita.dost.reader.toc.xml，
org.dita.dost.util.toc.xml，
org.dita.dost.writer.toc.xml —— 用于在帮助浏览器中建造导航树的 TOC XML 文件 - buildJavaDoc.xml —— 用于从 Ant 环境中运行 JavaDoc 工具的 ANT 文件
- buildJavaDoc.bat —— 用于运行 JavaDoc 工具的 BAT 文件
文件 org.dita.dost.index.toc.xml 仅仅是另一个内容目录，并且应当采用和其他 toc.xml 文件完全一致的格式（列表 14）。
列表 14. 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>
“doclet.toc.xml”是最主要的文件。此处的重要意义在于将这个内容目录定义为一个主要的 toc（列表 15）。
列表 15. 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>
当文档被查看时，使用这个方法同仅仅将额外的标题元素之间包括进来并没有任何区别（列表 16）。
列表 16. 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="~/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="~/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 并且选择 Help -> Help Contents。
运行 JavaDoc 来创建 HTML 文件
要生成 Java API 参考文档（HTML 格式）org.dita.dost：
- 通过执行命令在 Java 代码上运行 javadoc 功能，或者
- 运行 buildJavaDoc.bat 批处理文件（列表 17）。
列表 17. buildJavaDoc.bat
javadoc
-sourcepath src -d doc -doctitle "DITA XML" -overview src\overview.html
org.dita.dost.index org.dita.dost.invoker org.dita.dost.log
org.dita.dost.module org.dita.dost.pipeline org.dita.dost.platform
org.dita.dost.reader org.dita.dost.util org.dita.dost.writer
org.dita.dost.exception
将插件程序打包
每一个标题元素都通过导航列表中的一个入口在最终的文档中被反映出来。这些标题能够被嵌套（它们能够包含更多的标题），并且每一个标题都指向一个 HTML 文件。一旦您完成这些操作，那么您所需要做的就只剩下在图 1 所示的结构中为每一样东西打包（请注意插件程序目录的名称同 plugin.xml 中所定义的插件程序的标号和版本属性相匹配）。
图 1. 插件程序目录
出于方便的考虑，同时也是为了缩减文件的大小，Eclipse 允许您将所有的文档（HTML 文件）放置到一个名为 doc.zip 的 ZIP 压缩文件中，所以您就能够使用如图 2 所示的目录结构。
图 2. doc.zip 的目录结构
查看您的文档
测试您的插件程序的最简单的方法就是将整个目录（如上所述）拖放到 Eclipse Platform 的插件程序目录中。然后启动 Eclipse 并且选择 Help > Help Contents。您将得到一个具有插件程序的帮助窗口（和图 3 所示的内容相似）。
图 3. Help —— Eclipse SDK
注意
本文中所提供的信息是作为一名技术人员的我通过观察和实践总结出来的，并且并未提交给任何正式的 IBM 测试，也没有以任何形式的授权进行发布。
JavaTOC doclet 工具是一个公布的发明，其作者是 Mariana Alupului。这项发明是 IBM Intellectual Property 的一部分，并且被发表在 www.ip.com 上面。
这一信息的使用或者本文中所描述的这些技术的使用都是读者的责任，并且依赖于读者的能力将其应用到他们的操作环境之中。
小结
本文中所介绍的 JavaTOC doclet 能够被用来创作基于 HTML 的 Java API 参考帮助文档以及少量额外的文档元素。使用这一 doclet 能够容易的创建 Eclipse 平台文档，进而被用于创作面向现已存在的 Eclipse 帮助系统的 XML 和 HTML 输出格式。我们已经展示了如何使用 JavaTOC doclet 开发 Eclipse 平台文档。这个免费的开源解决方案能够是您的文档开发简单化，允许您工作于一个 doclet 并且生成自己的插件程序和参考文档。随着时间的推移，还将不断添加新的功能。
在 developerWorks XML 专区系列的下一篇文章《Java API 文档是如何在 DITA API 规范中被组织起来的》中，我将描述一个使用面向 Eclipse 插件程序帮助系统的 DITAdoclet 工具自动生成可搜索的 Java API 文档（TOC 导航）的过程。我们还将更加深入的学习 Java API 技术，一些来自 IBM 的更多增进，包括 Java DITA API 规范，以及它是如何被利用的。
下载
| 描述 | 名字 | 大小 |
|---|---|---|
| JavaTOC Doclet | JavaTOC.zip | 13KB |
浙公网安备 33010602011771号