技术标签: 文档 javadoc java html api eclipse
通过 JavaTOC doclet 生成的 Eclipse Javadoc API 参考文档结构
|
您能够通过运行 JavaTOC doclet 和 Javadoc 来生成 Java API 参考文档、内容目录(TOC)导航和插件程序结构。或者,您只需运行 JavaTOC doclet 就能够从现已存在的文档中生成 TOC 导航。
对于每一个您希望贡献给 Eclipse 帮助系统(Java API 参考小节)的插件程序来说,通常地,按照以下工作流程被处理:
Ant 是目前看来人人都在使用的 Java 建造系统。如果您还没有使用过 Ant 的话,请登录 Jakarta 网站,或者“Open Source Java: Ant”。
我最喜欢的运行 JavaTOC doclet 工具的方式就是通过 Ant 建造系统来进行的,但是在本文中,我将向您展示如何从命令提示行中使用 JavaTOC doclet。
|
JavaTOC Doclet Toolkit 1.0.0 版本为不熟悉 Ant 的用户提供了一个命令行接口,以方便他们使用这一工具集。
-doclet com.ibm.malup.doclet.config.TOCDoclet -docletpath C:/doclet/bin/TOCNavDoclet.jar |
-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' |
com.ibm.package1 com.ibm.package2 ... com.ibm.packageN |
source/../../package1/fileA.java,source/../../package2/fileB.java, , , source/../../packageN/fileN.java |
参数 | 描述 |
-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 文件。 |
使用 JavaTOC doclet 创建一个 XML TOC 文件
至此,我们已经完成了对 doclet 的讨论,下面我们来看一个实际的例子,使用 JavaTOC doclet 和 DITA-OT 1.3 源文件(DITA-OT1.3_src.zip)。
一个 TOC 文件通过将被标记的标题映射到个体的 HTML 文件上,定义了进入 HTML 内容文件的关键入口,并且扮演一组 HTML 内容目录的角色。由于这个 TOC 文件描述了如何导航 HTML 内容,所以它们有时被作为导航文件使用。一个插件程序能够拥有一个或者多个 TOC 文件。
运行 bat 文件:C:/doclet/JavaTOC>TOCDoclet_dost.bat(列表 5 至列表 8)。
javadoc @config @options @packages |
-doclet com.ibm.malup.doclet.config.TOCDoclet -docletpath C:/doclet/bin/TOCNavDoclet.jar |
-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 |
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
插件程序的名称、标号、版本以及提供者的名称值等都是从 -d、-doctitle、—version 和 —provider 属性中自动生成的(列表 10)。
# 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)。
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
现在,我们已经拥有了所有的插件程序文件,它们已经为 Eclipse 帮助系统而被标记出来。您拥有用于 Java API 参考文档的结构,这些文档使得一个 Eclipse 中的导航能够通过一个被编写为 XML 文档的内容目录(TOC)帮助插件程序。这种可浏览的和可搜索的需要通过使用 XML 的这一结构化的信息方法被满足。
该文档的左侧是索引,右侧是 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% 的插件程序帮助代码。
从 C:/doclet/ 目录中运行民命令提示行 JavaTOC doclet。 C:/doclet/JavaTOC>javadoc @tocdoclet options.org.dita.dost @packages (列表 13)。
-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)
文件 org.dita.dost.index.toc.xml 仅仅是另一个内容目录,并且应当采用和其他 toc.xml 文件完全一致的格式(列表 14)。
doclet.toc.xml”是最主要的文件。此处的重要意义在于将这个内容目录定义为一个主要的 toc(列表 15)。
列表 15. doclet.toc.xml
当文档被查看时,使用这个方法同仅仅将额外的标题元素之间包括进来并没有任何区别(列表 16)。
列表 16. org.dita.dost.index.toc.xml
在编辑源代码文件或者将新的 API 文档添加进源代码文件之后,您应当生成文档以确认和测试其结果正是您所期望的。
现在,请将您的插件程序拖放到平台的插件程序目录下,启动 Eclipse 并且选择 Help -> Help Contents。
要生成 Java API 参考文档(HTML 格式)org.dita.dost:
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 中所定义的插件程序的标号和版本属性相匹配)。
出于方便的考虑,同时也是为了缩减文件的大小,Eclipse 允许您将所有的文档(HTML 文件)放置到一个名为 doc.zip 的 ZIP 压缩文件中,所以您就能够使用如图 2 所示的目录结构。
测试您的插件程序的最简单的方法就是将整个目录(如上所述)拖放到 Eclipse Platform 的插件程序目录中。然后启动 Eclipse 并且选择 Help > Help Contents。您将得到一个具有插件程序的帮助窗口(和图 3 所示的内容相似)。
|
本文中所提供的信息是作为一名技术人员的我通过观察和实践总结出来的,并且并未提交给任何正式的 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 | HTTP |
文章浏览阅读119次。该楼层疑似违规已被系统折叠隐藏此楼查看此楼/***Getaparametervalue**@paramkeyString*@paramdefString*@returnString*/publicStringgetParameter(Stringkey,Stringdef){returnisStandalone?System.getProperty(ke..._java http隧道
文章浏览阅读913次。IP主机名备注192.168.117.14keepalived-master主节点192.168.117.15keepalived-slaver备节点192.168.117.100VIP1.主备节点均安装keepalived# yum install -y keepalived httpd2.主备节点均修改keepalived日志存放路径..._keepalived sendmail
文章浏览阅读469次。--==========================================--SPFILE错误导致数据库无法启动(ORA-01565)--========================================== SPFILE错误导致数据库无法启动 SQL> startup ORA-01078: failurein proce_ora01565 ora27046
文章浏览阅读6.1k次,点赞2次,收藏54次。功能测试基础知识总结_功能测试
文章浏览阅读3.2k次,点赞3次,收藏2次。pg 中文首字母排序_pg中文排序
文章浏览阅读3.1w次,点赞23次,收藏109次。本文主要讲解CONVERT函数_mysql convert
文章浏览阅读8.6k次,点赞2次,收藏2次。HTML5 的视频播放事件想必大家已经期待很久了吧,在HTML4.1、4.0之前我们如果在网页上播放视频无外乎两种方法: 第一种:安装FLASH插件或者微软发布的插件 第二种:在本地安装播放器,在线播放组件之类的 因为并不是所有的浏览器都安装了FLASH插件,就算安装也不一定所有的都能安装成功。像苹果系统就是默认禁用FLASH的,安卓虽然一开始的时候支持FLASH,但是在安卓4.0以后也开始不_微信开发者工具视频快进
文章浏览阅读5.4k次,点赞3次,收藏4次。在使用redis的过程常见错误总结1.JedisConnectionException Connection Reset参考这边文章:Connection reset原因分析和解决方案https://blog.csdn.net/cwclw/article/details/527971311.1问题描述Exception in thread "main" redis.clients...._jedisconnectionexception: java.net.socketexception: connection reset
文章浏览阅读8.3k次,点赞8次,收藏42次。目录1.Lua垃圾回收算法原理简述2.Lua垃圾回收中的三种颜色3.Lua垃圾回收详细过程4.步骤源码详解4.1新建对象阶段4.2触发条件4.3 GC函数状态机4.4标记阶段4.5清除阶段5.总结参考资料lua垃圾回收(Garbage Collect)是lua中一个比较重要的部分。由于lua源码版本变迁,目前大多数有关这个方面的文章都还是基于lua5.1版本,有一定的滞后性。因此本文通过参考当前..._lua5.3 gc
文章浏览阅读511次。最近家中的潮人,老妈闲着没事干,开始学玩电脑,引起他的各种好奇心。如看看新闻,上上微信或做做其他的事情。但意料之中的是电脑上会莫名出现各种问题?不翼而飞的图标?照片又不见了?文件被删了,卡机或者黑屏,无声音了,等等问题。常常让她束手无策,求助于我,可惜在电话中说不清,往往只能苦等我回家后才能解决,那种开心乐趣一下子消失了。想想,这样也不是办法啊, 于是,我潜心寻找了两款优秀的远程控制软件。两款软件...
文章浏览阅读1.8k次。二.初始化工作空间三.设置下载地址四.下载功能包此处可能会报错,请看:rosdep update遇到ERROR: error loading sources list: The read operation timed out问题_DD᭄ꦿng的博客-程序员宅基地接下来一次安装所有功能包,注意对应ROS版本 五.编译功能包isolated:单独编译各个功能包,每个功能包之间不产生依赖。编译过程时间比较长,可能需要几分钟时间。此处可能会报错:缺少absl依赖包_ros18.04 安装ca
文章浏览阅读4.1k次,点赞3次,收藏7次。Haobor2.2.1配置(trivy扫描器、镜像签名)docker-compose下载https://github.com/docker/compose/releases安装cp docker-compose /usr/local/binchmod +x /usr/local/bin/docker-composeharbor下载https://github.com/goharbor/harbor/releases解压tar xf xxx.tgx配置harbor根下建立:mkd_init error: db error: failed to download vulnerability db: database download