Java API 参考文档，第 3 部分,通过运行 JavaTOC doclet 和 ANT 生成的 Eclipse Javadoc API 参考结构...

使用 JavaTOC doclet 生成 Eclipse 插件程序（Javadoc API 参考文档）

Eclipse 平台帮助系统允许您使用 org.eclipse.help.contributions 扩展点将您的插件程序贡献到在线帮助上。您既可以将您的代码插件程序贡献为在线帮助的一部分，也可以单独的将它自己的文档插件程序贡献给在线帮助。您自己的文档插件程序提供了处理一份源代码的好处，并且将生成处理过程从开发处理过程中分离出来。在开发和文档人员分属于不同团队的情况下，或者您希望降低文档源和源代码之间依赖性的情况下，考虑这种方法是很有益处的。

org.eclipse.help.contributions 扩展点提供了四个元素，您可以通过它们贡献您的帮助：topics（主题）、infoset（信息集合）、infoview（信息视图）和 actions（动作）。信息集合和行动贡献指定一个包含贡献细节的被关联的 .xml 文件。

设计约束

无论您是技术作者还是开发人员，您都希望为用户提供一个完整记录的、易于搜索和浏览的 Java API 参考。

您能够运行 JavaTOC doclet 来生成 TOC XML 导航文件和 Javadoc，或者运行该工具来生成 TOC XML 导航文件并且使用由开发人员所生成的 Javadoc。本文提出一种在 Eclipse 开发环境中使用标准的 Javadoc 生成器向导 来为 Java API 参考文档创建 Javadoc 并且为 TOC XML 导航文件创建 JavaTOC doclet 的解决方案。

本文展示了如何在 Eclipse 中通过 Custom doclet 向导和 Ant 编译系统运行 JavaTOC。如果您没有处理过 Ant，那么请您登录 Jakarta 网站，或者“Open Source Java: Ant”.

工作流程

将 JavaTOC 插件程序编译工具（JavaAPITools）添加到您的工作区中：

• 找到您的 Eclipse 版本所使用的工作区目录。典型的情况下，它位于 Eclipse 被安装的目录下一个被称作“workspace”的子目录中。如果您使用一个快捷方式或者脚本来启动 Eclipse 的话，那么它就位于该快捷方式或者脚本所在的当前目录下一个被称作“workspace”的子目录中。
• 下载包（JavaAPITools）并将其解压到您的工作区中。于是创建一个被称为“JavaAPITools”的项目。
• 将“JavaAPITools”项目以及您希望处理的 Java 项目导入到您的 Eclipse 工作区中。

使用 Import Wizard （导入向导）将一个现已存在的 Java 项目导入到工作区中。在这个例子中，我创建了一个新的 Java 项目并且添加到 src 文件夹中。 DITA Open Toolkit 源代码将 DITA 内容（映射和主题）转化到可交付使用的格式。您可以从 Download 资源中下来这个插件程序。

使用 Eclipse Javadoc 生成器向导（Standard Doclet）创建 Javadoc

下列步骤展示了如何在一个 Eclipse 开发环境中使用标准的 Javadoc Doclet 生成 Javadoc：

• 在 Eclipse 中，在左侧面板上选择用于生成 Javadoc 所需要的源代码插件程序。
• 右键单击被选择的插件程序，并且从下拉列表中选择 Export。窗口 Export 随即打开。
• 选择 Javadoc 并且点击 Next。窗口 Generate Javadoc 随即打开。
• 在 Generate Javadoc 窗口中选择您希望导出到 JAR 文件中的包。这一列表是由工作台选择初始化的。一次只能够选择一个项目，这是因为在运行 Javadoc 工具时一次只能使用一个项目的类路径。（请参见图 1 所示）
• 选择成员的可见性（通常是 Package 和 Public）。
• 选择 Use Standard Doclet 开启 Javadoc 命令和标准的 doclet （默认设置）。
• 目的文件：选择目的文件，标准的 doclet 将把生成的文档写入其中。目的文件是一个 doclet 指定参数，因此当使用自定义 doclet 时是无效的。
  举例来说，目的文件可以是“doc.dita.dost.doc/topics”。（请参见图 2 所示）

图 1. Javadoc 生成器向导 （Standard Doclet）


图 2. 目的文件


由 Javadoc 生成器向导所提供的支持选型列表：

选项	描述
文档标题	指定一个文档的标题。
生成使用页	如果您希望文档中包含一个 Use 页，那么请选择这一选项。
生成层次树	如果您希望文档中包含一个 Tree 页，那么请选择这一选项。
生成导航栏	如果您希望文档中包含一个导航栏（顶部或者底部），那么请选择这一选项。
生成索引	如果您希望文档中包含一个 Index 页，那么请选择这一选项。
生成字母索引	创建一个字母索引。当 Generate Index 被选中时有效。
@作者	如果您希望文档中包含一个被记录的 @author 标签，那么请选择这一选项。
@版本	如果您希望文档中包含一个被记录的 @version 标签，那么请选择这一选项。
@反对	如果您希望文档中包含一个被记录的 @deprecated 标签，那么请选择这一选项。
反对列表	如果您希望文档中包含一个 Deprecated 页，那么请选择这一选项。当 @deprecated 选项被选中时有效。
选择 Javadoc 应当创建链接的参考类	指定当其他类型被参考时，其他文档 Javadoc 用当创建的链接。 选择所有：创建到所有其他文档位置的链接； 清除所有：不创建到其他文档位置的链接； 配置：配置一个被参考的 JAR 或者项目的 Javadoc 位置。
风格	选择要使用的风格

• 点击 Finish 完成 Javadoc 的生成，或者点击 Next 指定另外的 Javadoc 生成器选项。

注释：如果您希望获得更多的信息，请参见：Javadoc generation — Eclipse Help Platform

用于输出文件的目的文件夹

• doclet 为插件程序文件生成输出的 HTML 文件 "org.dita.dost/org.dita.dost.doc/topics/"，即是当前的插件程序文件的目录。

使用 Eclipse Javadoc 生成器向导和 JavaTOC doclet （Custom Doclet）创建 TOC XML 导航和 Javadoc 插件程序文件

下面的步骤将展示如何在 Eclipse 开发环境中将自定义的 doclet （JavaTOC doclet）和 Javadoc 结合起来使用：

• 在 Eclipse 中，在左侧面板上选择用于生成 Javadoc 所需要的源代码插件程序。
• 右键单击被选择的插件程序，并且从下拉列表中选择 Export。窗口 Export 随即打开。
• 选择 Javadoc 并且点击 Next。窗口 Generate Javadoc 随即打开。
• 在 Generate Javadoc 窗口中选择您希望导出到 JAR 文件中的包。这一列表是由工作台选择初始化的。一次只能够选择一个项目，这是因为在运行 Javadoc 工具时一次只能使用一个项目的类路径。
• 选择成员的可见性（通常是 Package 和 Public）。
• 选择 Use Custom Doclet 并且将 doclet 的 Qualified 类型名称添加到 Doclet 名称： com.ibm.malup.doclet.config.DITADoclet ，以及将 doclet 类所需要 Classpath 添加到 Doclet 类路径： <eclipse_workspace>/JavaAPITools/bin/JavaTOC.jar
  注释：<eclipse_workspace> 是 Eclipse 工作区的绝对路径（C:/eclipse/workspace）。
  • 目的文件：选择目的文件，标准的 doclet 将把生成的文档写入其中。目的文件是一个 doclet 指定参数，因此当使用自定义 doclet 时是无效的。
    举例来说，目的文件可以是“doc.dita.dost.doc/topics”。
• 点击 Next。

图 3. Javadoc 生成器向导（Custom Doclet）


图 4. 目的文件

额外的 Javadoc 选项

• 对于 Extra （额外的） Javadoc 选项（白色间隔的路径名称必须被引号括起来）；从列表 1 中添加内容。（对于我们的例子来说是 org.dita.dost 插件程序。）
  1. -d <destination_directory> 为生成的文档指定目的文件的目录。默认情况下，即是当前所在目录（一个由 “.” 指定的路径名）。
  2. -pluginid <plugin_id> 包括用于 Eclipse 插件程序标识符页的标识符。
  3. -doctitle <html_code> 包括用于 Eclipse 插件程序名称页的标题。
  4. —overview <file> 指定插件程序版本标识符的细节。
  5. —version <plugin_version> 指定插件程序版本版本标识符的细节。
  6. -provider <plugin_provider> 指定插件程序提供者名称的细节。
  7. -anchor <file> 链接是通过到一个目录的完整参考被指定的，例如：“../the_other_plugin_id/path/to/toc.xml#anchor_id”。
  8. -notree 如果您要为一个大的项目生成文档，那么请指定创建多个 XML TOC 文件。

列表 1. 额外的 Javadoc 选项

-d C:/eclipse/workspace/org.dita.dost/org.dita.dost.doc/ -pluginid org.dita.dost.doc -doctitle 'Building DITA output' -version '7.0.0.1' -provider 'IBM' -subsystemtoc

用于输出文件的目的文件目录

• doclet 为插件程序生成输出的 TOC XML 文件以及其他位于 org.dita.dost/org.dita.dost.doc/ 文件夹（即是您当前的插件程序目录）中的若干有用的文件。由 JavaTOC doclet 所创建的文件包括：
  • plugin.xml
  • plugin.properties
  • build.properties
  • .project
  • META-INF/MANIFEST.MF
  • primary.plugin.toc.xml
  • org.dita.dost.xxx.toc.xml —— 用于在帮助浏览器中编译导航树的 TOC XML 文件。
• 插件程序的名称、标识符、版本以及提供者名称的值都是从 -d, -doctitle, —version 和 —provider 属性中自动被生成的。
• 插件程序列表文件通过将字符串替换为一个关键字（例如 %pluginName）使它们被具体化，并且在 plugin.properties 文件中创建一个入口： Plugin.name = Online Help Sample Plugin

使用 JavaAPITools （build.xml & JavaTOC doclet） 和 ANT 创建您的文档插件程序

JavaAPITools 的主要目的就是和 Javadoc 结合起来，为公共的 API 参考文档和将这些参考文档集成到 Eclipse 帮助系统所必需的所有的 Eclipse 插件程序文件（包括用于 Javadoc 的 TOC XML 导航文件）创建一个 NEW DOCUMENTATION 插件程序。

安装插件程序编译工具（buildAPITools）

JavaAPITools 包为创建 Eclipse 文档插件程序提供了一个 Eclipse 编译脚本。该脚本使您能够在 Eclipse 中转化 Java 项目插件程序，并且将 Eclipse 目标运行时间用于对它们的测试。Javadoc 的生成通过在您的插件程序中创建一个被称作 build.xml 的 ANT 脚本来完成。这个 ANT 脚本要求 JavaAPITools build.xml 编译工具必须被放置在您的开发系统（工作区）中的某个位置。同样，该脚本必须能够决定得到的 xxx.doc 插件程序如何被打包用于部署部署。

• 下载该包，在您的工作区中创建一个“JavaAPITools”项目，并且将该包解压到这个项目中。
• 将插件程序导入到您的 Eclipse 工作区中。在我们的例子中，我创建了一个新的 Java 项目并且添加到 src 文件夹中。 DITA Open Toolkit 源代码将 DITA 内容（映射和主题）转化到可交付使用的格式。您可以从 Download 资源中下来这个插件程序，也可以在您的项目范例上面运行。

决定插件程序部署包

在 Eclipse 3.2 之前，被生成的 Javadoc 将被同 HTML 文件一起被保存在一个 doc.zip 文件中。自从 3.2 版本开始，整个文档插件程序就被单独存放为一个 .jar 文件，其中还包括将同 Eclipse 插件程序文件一起被包括进 doc.zip 文件的所有文件：manifest.mf、plugin.xml、plugin.properties 等。

自从 Eclipse 3.1 以来，插件程序既可以部署为一个包含独立文件（包括一个或者多个 jar 文件）的目录，也可以被部署为一个单独的 jar 文件。

列表 2. build.properties

bin.includes = META-INF/,/ .project,/ plugin.xml,/ toc.xml,/ plugin.properties,/ doc.zip,/ bin/

注释：如果最初的插件程序被部署为一个文件夹，那么 build.properties 文件就应当包括 doc.zip 文件。如果插件程序被部署为一个单独的 .jar，那么 build.properties 就“不”应当包含 doc.zip 而应当包含在一个 doc.zip 文件中被创建的 droot 目录和文件夹。

此外，包括这样一个 doc 插件程序的 .doc-feature 插件程序也必须在用于插件程序的 feature.xml 文件中包含 unpack="false" 属性。

创建、管理和运行 ANT 编译文件

• 从 builAPITools 中右键单击 build.xml 并且选择 Run As > External Tools。在 Builders 部分中，选择 New Lunch Configuration .. 并且创建一个新的 Ant Build 配置。
• 在得出的配置对话框中，将名称设置为唯一性的内容（例如：Build Plugin Documentation）。在启动配置 Main 标签中，浏览工作区并且从 JavaAPITools 中选择 build.xml。向 Base directory 中添加值：${project_loc}。

图 5 中显示了 ANT 启动配置对话框中的 Main 标签。

图 5. 设置运行 ANT 编译文件

• 参数：
  • 参数 —verbose 允许您跟踪一个不工作的特定命令的信息。参数 —quiet 阻止了大部分不是源于编译文件中的 echo 任务的消息。参数 -debug 打印 Eclipse Console 中的调试信息。
  • 在编译脚本被执行之前，参数 —Dbuild.toc.tree=true 将属性 —build.toc.tree 的值赋为 true。它将在多个文件中只创建一个首要的 TOC XML 文件（xxx.toc.xml）。

创建 build.xml ANT 文件

build.xml 脚本定义了为被关联的组件插件程序生成 Javadoc 所需要的所有信息，或者创建 doc.zip 文件，或者将生成的文件复制到插件程序的根目录中。获得这一文件中能够被使用的任务的完整文档，请参见：JavaAPITools/build.xml。
这一文件的初始内容应当是：

列表 3. build.xml

1. <?xmlversion="1.0"encoding="UTF-8"?>
3. <!--**************************************************************-->
4. <!--ANTbuildfileforEclipsetocfilesanddocumentationsplugins-->
5. <!--MarianaAlupului10/08/2006-->
6. <!--**************************************************************-->
8. <projectname="build"default="main">
9. <echomessage="${ant.project.name}:${ant.file}"/>
14. <!--
15. ****************************************************************************
16. Themainbuildtarget.
17. ****************************************************************************
18. -->
19. <targetname="main"
20. depends="setup,
21. useManifestMF,usePluginXML,badPlugin,
22. runJavaDoc,runJavaTOCDoclet,
23. deployPlugin,
24. copyPlugin,
25. cleanProject"
26. description="BuildPlug-inDocumentation">
27. <echomessage="${ant.project.name}:${ant.file}"/>
28. </target>
29. Comment:
30. The"main"targetexecutesthetargetsinthedependsattributeinthe
31. ordertheyappear(fromlefttoright).Keepinmindthatitispossiblethat
32. atargetcangetexecutedearlierwhenanearliertargetdependsonit:(setup,
33. useManifestMF,usePluginXML,badplugin,runJavaDoc,runJavaTOCDoclet,generateZip,
34. copyPlugin,cleanProject).
36. <targetname="init"description="Projectvariables">
37. <propertyname="ECLIPSE_HOME"value="../../"/>
38. <propertyname="build.plugin"value="jar"/>
39. <propertyname="project.dir"value="${basedir}"/>
40. <propertyname="build.toc.tree"value="false"/>
41. </target>
43. <targetname="setup"depends="init"description="SetuptheProject">
44. <tstamp>
45. <formatproperty="now"pattern="dMMMMyyyyHH:mm:ssaa"/>
46. </tstamp>
47. <echo>===StartingBuildingPluginDocumentation===</echo>
48. <echo>===${now}===</echo>
49. </target>
50. Comment:
52. Antbuildfileprovidesaccesstoallsystempropertiesasiftheyhad
53. beendefinedusinga<property>task.
55. <targetname="validatePlugin"description="Selectplugin.xmlormanifest.mf">
56. <conditionproperty="plugin.xml.exists">
57. <availablefile="${project.dir}/plugin.xml"/>
58. </condition>
60. <conditionproperty="manifest.mf.exists">
61. <availablefile="${project.dir}/META-INF/MANIFEST.MF"/>
62. </condition>
64. <conditionproperty="invalid.plugin">
65. <and>
66. <not>
67. <issetproperty="plugin.xml.exists"/>
68. </not>
69. <not>
70. <issetproperty="manifest.mf.exists"/>
71. </not>
72. </and>
73. </condition>
74. </target>
76. <targetname="useManifestMF"
77. depends="validatePlugin"
78. if="manifest.mf.exists"
79. description="GetpluginnamefromMANIFEST.MF">
80. <loadpropertiessrcFile="${project.dir}/META-INF/MANIFEST.MF">
81. <filterchain>
82. <linecontains>
83. <containsvalue="singleton"/>
84. </linecontains>
85. <replacestringfrom=";"to=".doc"/>
86. <replacestringfrom=""to="/>
87. <replacestringfrom="singleton:=true"to="/>
88. </filterchain>
89. </loadproperties>
91. <propertyname="plugin.name"value="${Bundle-SymbolicName}"/>
92. <loadpropertiessrcFile="${project.dir}/META-INF/MANIFEST.MF"/>
93. <propertyname="bundle.name"value="${Bundle-Name}"/>
94. <propertyname="version.name"value="${Bundle-Version}"/>
95. <propertyname="vendor.name"value="${Bundle-Vendor}"/>
96. </target>
98. <targetname="usePluginXML"
99. depends="validatePlugin"
100. if="plugin.xml.exists"
101. unless="manifest.mf.exists"
102. description="Getpluginnamefromplugin.xml
103. ifMANIFEST.MFdoesnotexist">
104. <xmlpropertyfile="${project.dir}/plugin.xml"/>
105. <propertyname="plugin.name"value="${plugin(id)}.doc"/>
106. <propertyname="bundle.name"value="${plugin(bundle-name)}"/>
107. <propertyname="version.name"value="${plugin(bundle-version)}"/>
108. <propertyname="vendor.name"value="${plugin(bundle-vendor)}"/>
109. </target>
111. <targetname="badPlugin"
112. depends="validatePlugin"
113. if="invalid.plugin"
114. description="Processingendsifpluginisinvalid">
115. <failmessage="ERROR::Plugin${project.dir}isinvalid.
116. Noplugin.xmlwasfound."/>
117. </target>
118. Comment:
119. TheAntbuildfileprovidesaccesstotheMANIFEST.MFfileor/and
120. totheplugin.xmlfile,andusestheexistingplug-inname,id,version
121. nameandvendornamefromtheexistingJavaplugin.AnErrorappears
122. inyourconsoleifnoplugin.xmlorMANIFEST.MFwasfound.
124. <targetname="runJavaDoc"
125. depends="validatePlugin"
126. unless="invalid.plugin"
127. description="GenerateJavaDocAPIdocumentations">
128. <mkdirdir="${plugin.name}"/>
129. <mkdirdir="${plugin.name}/META-INF"/>
130. <echo>SUCCESS:Createdirectory${basedir}/${plugin.name}</echo>
131. <javadoc
132. access="public"
133. author="true"
134. destdir="${plugin.name}/topics"
135. nodeprecated="false"
136. nodeprecatedlist="false"noindex="false"nonavbar="false"
137. notree="false"
138. packagenames="*"
139. source="1.4"
140. sourcepath="src"
141. splitindex="true"use="true"version="true"/>
142. </target>
143. Comment:
144. SeeTableofsupportedoptionsprovidedbyJavadocGenerationwizardif
145. youwanttoaddmoreoptionstorunthestandardJavadoc.
147. Example:
148. ToaddtheAuthorname(@author)tothedocumentation,addauthor="true".
150. <targetname="runJavaTOCDoclet"
151. unless="invalid.plugin"
152. description="GenerateEclipseXMLTOCfiles">
153. <propertyname="buildAPITools"value="../JavaAPITools/bin/JavaTOC.jar"/>
154. <echo>EndPhaseIStandardDoclet-StartPhaseIIJavaTocDoclet...</echo>
155. <!--
156. <loadpropertiessrcFile="${project.dir}/plugin.properties"/>
157. <propertyname="plugin.link"value="${Plugin.link_to}"/>
158. -->
159. <javadoc
160. access="public"
161. classpath="."
162. sourcepath="src"
163. notree="${build.toc.tree}"
164. packagenames="*">
165. <doclet
166. name="com.ibm.malup.doclet.config.TOCDoclet"
167. path="${buildAPITools}">
168. <paramname="-d"value="${basedir}/${plugin.name}"/>
169. <paramname="-plugintitle"value="APIReference(${bundle.name})"/>
170. <paramname="-pluginid"value="${plugin.name}"/>
171. <paramname="-version"value="${version.name}"/>
172. <paramname="-provider"value="${vendor.name}"/>
173. <!--
174. <paramname="-anchor"value="${plugin.link}"/>
175. -->
176. </doclet>
177. </javadoc>
178. </target>
179. Comment:
180. SeeListing1.ExtraJavadocoptionsifyouwanttoaddmoreoptionsto
181. runtheJavaTOCdoclettool.
183. Example:—overview<file>
184. <paramname="-overview"value="${basedir}/${plugin.name}/overview.html"/>
186. Example:—anchor<file>
187. <paramname="-anchor"value="../the_other_plugin_id/path/to/toc.xml#anchor_id"/>
188. <targetname="deployPlugin"
189. description="Ifplug-inispackagedasadirectory(unpacked)">
190. <loadfilesrcFile="${basedir}/build.properties"
191. property="build_properties"/>
192. <conditionproperty="deployPlugin">
193. <containsstring="${build_properties}"substring="doc.zip"/>
194. </condition>
195. <antcalltarget="createDocZip"/>
196. </target>
198. <targetname="createDocZip"
199. if="deployPlugin"
200. description="Theplug-inispackagedasadirectory">
201. <echo>==The.docplug-inistobedeployedasadirectory==</echo>
202. <zipdestfile="${project.dir}/${plugin.name}/doc.zip"
203. basedir="${plugin.name}">
204. <includename="topics/**"/>
205. <includename="images/**"/>
206. <includename="pdf/**"/>
207. <includename="*.css"/>
208. </zip>
209. <deletedir="${project.dir}/${plugin.name}/topics"/>
210. </target>
211. Comment:
212. TheAntbuildfileprovidesaccesstothebuild.propertiesfile
213. (ifthepluginistobedeployedasadirectory,orasajarfile)andcreates
214. thedoc.zipfile.
216. <targetname="copyPlugin"
217. description="Copytheprojecttoworkspace">
218. <copyincludeemptydirs="true"
219. todir="${ECLIPSE_HOME}/workspace/${plugin.name}">
220. <filesetdir="${plugin.name}"
221. excludes="**/*.launch,**/buildJavaDoc.bat"/>
222. </copy>
223. </target>
225. <targetname="cleanProject"description="Cleanstheproject">
226. <deletedir="${project.dir}/${plugin.name}"/>
227. <deletedir="../buildAPITools/${plugin.name}"/>
228. <echo>===EndBuilding${plugin.name}Plug-inDocumentation===</echo>
229. <echo>===${now}===</echo>
230. </target>
231. Comment:
232. Copytheprojecttoyourworkspace.
235. </project>

自动编译插件程序

• 加亮您的插件程序项目。
• 点击 Run > External Tools > External Tools > Build Plugin Documentation。
  • 随着编译的进行，运行注释和错误都出现在 Console 视图中。
  • 如果您在控制台中看到一个“BUILD FAILED”的错误，请您进行修改并再次编译，直到在控制台消息底部看到“BUILD SUCCESSFUL”提示为止。
  • 在成功编译（在您的开发环境中）文档插件程序（没有 ANT 错误）之后，应该有一个用于 HTML 文件的 /topics 文件夹和一个根目录下的 doc.zip 文件以及插件程序 manifest 文件。
  • 编译属性将包括所有的 toc*.xml 文件、plugin.properties、META-INF 和 .project 文件。如果一个 doc.zip 文件被创建的话，那么 build.properties 文件也将包括 doc.zip （不加修改）。如果插件程序作为一个单独的 jar 文件被部署的话，那么 build.properties 文件就必须还包括被创建的（主题）顶层目录，而且不包括 doc.zip 文件。

用于输出文件的目标文件目录（org.dita.dost.doc）

• 对于我们的例子来说（org.dita.dost.doc 插件程序），编译文件为插件程序生成输入的 XML 文件以及其他若干有用的文件到 workspace/org.dita.dost.doc 目录下，该目录即是您当前的插件程序目录。
• 将 build.toc.tree 的值从 false 修改为 true。ANT 编译程序以两种方式生成输出：
  
  

  <property name="build.toc.tree" value="false" />

  <property name="build.toc.tree" value="true" />

  .project plugin.xml plugin.properties META-INF/MANIFEST.MF topics/ —— 所有的 HTML 文件。 doc.zip primary.plugin.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.bat —— 用于运行 JavaDoc 工具的 BAT 文件。

  .project plugin.xml plugin.properties META-INF/MANIFEST.MF topics/ —— 所有的 HTML 文件。 doc.zip org.dita.dost.doc.toc.xml —— 用于在帮助浏览器中编译导航树的主要的 TOC XML 文件。 buildJavaDoc.bat —— 用于运行 JavaDoc 工具的 BAT 文件。

  
  
  
• 您可以通过修改 ANT 编译文件来添加更多的特性：
  • 在 Java 项目 plugin.properties 上添加 Plugin.notree = false；
    
    

    Plugin.name = DITA Dost Plugin.providerName = I.B.M. Plugin.link_to = ../com.ibm.xde.mda.doc/primary.plugin.toc.xml#api Plugin.anchor_id = api Plugin.notree = false

    
    
  • 在 build.xml 上添加：
    
    
    
    

    <loadproperties srcFile="${project.dir}/plugin.properties"/> <property name="plugin.link" value="${Plugin.link_to}" />

    
    

将插件程序导入您的工作区

您可以使用 Import Wizard （导入向导）将文档插件程序导入到您的工作区中。

• 从主菜单栏中选择 File > Import...。导入向导窗口即被打开。
• 选择 General > Existing Project into Workspace 并且点击 Next。
• 选择根目录并且点击 Browse 定位到 Workspace 目录。
• 在 Projects 下选择 org.dita.dost.doc 要导入的项目。
• 点击 Finish 启动导入过程。

图 6. 将插件程序导入工作区 1


图 7. 将插件程序导入工作区 2


图 8. 将插件程序导入工作区 3

测试 Java API 参考插件程序

• 设置目标运行时间环境：
  • 选择 Window > Preferences > Plug-in Development > Target Platform。
  • 将 Location 设置为主的 eclipse 目录，并且将外部安装的产品放置其中。在 Eclipse 目录下将会出现一个插件程序的列表（这一步骤需要一段时间）。
  • 点击 OK 保存 Target Platform （目标平台）的设置。
• 从 Plugin Development （插件程序开发）透视图中，通过选择 Run > Run 创建一个 Run 配置。这一操作将启动 Run 配置页面。
  • 点击 Eclipse Application 配置，然后点击 New 按钮，将其命名为任何一个标识符以作为测试 JavaTOCdoclet Eclipse Plugin。我们将调用这个 Test Plugin Doc。
  • 在 Main 栏中的位置区域下面，选择一个工作区目录。在您使用目标运行时间时的信息将被写入到这个工作区中，包括 .metadata 文件夹下的 .log 文件。
  • 在 Program to Run 下面选择 Run a product，并且选择 org.eclipse.platform.ide。
  • 在 Plug-ins 栏上选择 Choose plug-ins and fragments to launch from the list。
  • 在 Workspace Plug-ins 下面选择您希望测试的插件程序。这一选项允许您测试您的本地插件程序，即使该插件程序是新的而且并没有同目标运行时间一起被安装。
  • 保持 External Plug-ins 列表内容不变。
  • 选中 Add new workspace plug-ins to this launch configuration automatically 复选框。
  • 点击 Apply 保存这些改变。
  • 转换到 Plug-in Development perspective 并且选择 Run > Run 。
    • 选择您所创建的 Run 配置（Test Plugin Doc）并且点击 Run。目标运行时间将会启动。这意味着您的外部产品将会启动，但是将拥有一个本地插件程序的副本而不是产品中的版本。
    • 注释：一旦您运行过一次您的插件程序，Run 配置（Test Plugin Doc）就将出现在 Run History 中，所以您能够通过 Run > Run History > Test Plugin Doc 启动目标运行时间，或者您也可以使用工具栏中的图标。
    • 
    • 默认情况下，将启动目标平台中的每一个插件程序以及您工作区中所有打开的插件程序项目。这一默认设置已经足够了。

查看您的 Java API 参考文档

从新的 Eclipse 测试平台中选择：Help > Help Contents。您将看到如图 9 所示的帮助窗口，其中添加了您的插件程序（类似图 2 中所示的那一个）。

图 9. 帮助 —— Eclipse SDK

打包插件程序

在您完成以上所有操作之后，剩下的就是使用 Workbench User Guide （工作台用户向导）将结构中的所有内容进行打包，Export wizard （导出向导）。该向导帮助您从 Eclipse 工作台中导出资源。

注意

• 这一文档中所提供的信息是基于我作为一名技术作者的观察和手法，并没有提交到任何正式的 IBM 测试并作为 “AS IS”被分发，没有任何类型的授权、表达或暗示。
• JavaTOC doclet 工具是一个被发布的发明创造，其作者是 Mariana Alupului。该发明创造是 IBM Intellectual Property 的一部分，并且被发布在 www.ip.com 上面。
• 这一信息的使用或者文档中所描述的任何技术的执行都由读者自行负责，并且取决于作者将它们评价和结合到其操作环境中的能力。

小结

用于 Java API 规范的源文档注释是属于编程人员的，并且它们被编程人员和技术人员所共同编辑。

本文中所提出的 JavaTOC Doclet 能够被用来生产基于 HTML 的帮助文档，以及少量额外的文档元素。使用这一 doclet，能够轻易的创建 Eclipse 平台文档，然后将其用于为现已存在的 Eclipse 帮助系统生产 XML 和 HTML 输出格式。

我已经向您展示了如何使用 JavaTOC doclet 开发 Eclipse 平台文档，但并没有向您展示如何记录这些源代码。生成的文档应当是专业质量的，所以您需要完成最重要的工作；为完整记录的 Java API 参考完整的记录开发者的源代码。这一免费的开放源代码解决方案能够简化您的文档开发过程，允许您对 doclet 进行处理，并且拥有为您所生成的插件程序结构、TOC 导航和 HTML 文件。

在 developerWorks XML 专区即将发布的系列文章中，我将描述一个自动生成可搜索的 Java API 文档（TOC 导航）的处理过程，它使用 DITAdoclet 工具，面向 Eclipse 插件程序帮助系统。“How Java API Documentation is organized in DITA API specialization”将为下载提供 DITAdoclet 工具并且解释如何使用它来从 Java 源代码中生成 Java DITA API 文件和 XHTML 输出。我们还将更加深入的考查 Java API 参考文档技术，以及某些来自 IBM 的附加值增进（例如：Java DITA API 特化作用），以及如何对其加以利用。

下载

描述	名字	大小	下载方法
JavaTOC doclet	JavaAPITools.zip	261KB	HTTP
JavaTOC 示例	org.dita.dost.zip	323KB	HTTP