技术标签: 文档 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 |
文章浏览阅读497次。AOP实现权限拦截注解名称:CheckUnSysAdmin注解实现类:CommonAspectController层方法上引入注解名称:CheckUnSysAdminpackage com.sf.XWFS.aop;import java.lang.annotation.*;/** * @author cc * Desc 校验除超管外的角色,都进行拦截 */@Documented@Retention(RetentionPolicy.RUNTIME)@Target(ElementType_apo拦截控制层
文章浏览阅读52次。时隔4个月后,瑞星杀毒造假案又有了戏剧性的变化。近日,瑞星杀毒造假案的主角——北京市公安局网监处原处长于兵的二审结果仍维持一审的死缓判决。而据于兵的最新供认资料,相当一部分病毒是杀毒软件公司自己的科技力量研制的。于兵供认,瑞星公司向其行贿时就提出条件,由公安机关发出病毒警报,提示用户下载该公司杀毒软件进行杀毒,而病毒则是由瑞星公司“研制”的。“其实这是杀毒软件行业里的公开秘密。”国内一家知名...
文章浏览阅读6k次,点赞4次,收藏35次。考试重点1. 密码体制分类对称密码体制和非对称密码体制;2. DES和AES算法的特点(结构、密钥长度,分组长度,DES弱密钥)及其过程(置换过程,S盒查表过程),AES的轮结构DESDES结构首先是一个初始置换IP,用于重排明文分组的64比特;相同功能的16轮变换,每轮都有置换和代换;第16轮的输出分为左右两半并被交换次序;最后经过一个逆初始置换产生64比特密文;DES结构图如下:密钥长度:56分组长度:64DES弱密钥:待续了解即可DES 分组长度_移位密码和vigenere密码的异同是什么
文章浏览阅读2.7w次,点赞97次,收藏158次。系统功能包括管理员服务端:首页、轮播图管理、公告信息管理、系统用户(管理员、租客用户、房主用户)资源管理(新闻列表、新闻分类列表)模块管理(房源信息、房源咨询、租赁申请、入住信息、房租信息、反馈信息、通知信息、房屋类型)个人管理;用户客户端:首页、公告信息、新闻资讯、房源信息等功能。_微信小程序租房平台怎么弄
文章浏览阅读417次。文章目录一、禁止鼠标右键菜单二、禁止鼠标选中三、鼠标事件对象四、鼠标事件对象clientXpageXscreenX五、常用键盘事件一、禁止鼠标右键菜单<body> <script> document.addEventListener('contextmenu', function (e) { e.preventDefault(); }) </script></body>二、禁止_js鼠标点击事件菜鸟教程
文章浏览阅读7.1k次,点赞15次,收藏100次。PID算法中位置环与位置速度双环的对比分析_偏位置环控制速度
文章浏览阅读235次。A Key Volume Mining Deep Framework for Action Recognition_a key volume mining deep framework for action recognition
文章浏览阅读3.9k次。广告关闭腾讯云11.11云上盛惠 ,精选热门产品助力上云,云服务器首年88元起,买的越多返的越多,最高返5000元!2、python生成目录树上述 cmd 方式虽然可以生成目录树,但是并不美观,让我们用 python 实现。 2.1 标准库pathlib介绍python有一个标准文件路径处理库 os.path ,从 python3.4 开始,python 又加入了一个标准库 pathlib ,该库..._python创建一个窗口
文章浏览阅读5.1k次,点赞5次,收藏10次。时序图(Sequence Diagram)是显示对象之间交互的图,这些对象是按时间顺序排列的。顺序图中显示的是参与交互的对象及其对象之间消息交互的顺序。时序图中包括的建模元素主要有:角色(Actor)、对象(Object)、生命线(Lifeline)、控制焦点(Focus of control)/ 激活(Activation)、消息(Message)、组合片段(Combined Fragments_使用powerdesiger 画出时序图有接口 控制
文章浏览阅读1.2k次。文章目录一. 动态分区概述1.1 原理1.2 使用方式1.3 动态分区规则参数1.4 创建历史分区规则1.5 注意事项二. 案例2.1 案例12.2 案例22.3 案例3参考:一. 动态分区概述动态分区是在 Doris 0.12 版本中引入的新功能。旨在对表级别的分区实现生命周期管理(TTL),减少用户的使用负担。目前实现了动态添加分区及动态删除分区的功能。动态分区只支持 Range 分区。名词解释:FE:Frontend,Doris 的前端节点。负责元数据管理和请求接入。BE:Backend_dynamic_partition.history_partition_num
文章浏览阅读309次。笔记_禅道的运行日志放在哪
文章浏览阅读4.3w次,点赞79次,收藏882次。我们要使用这些知识实现一个简单的网页设计,利用HTML的a标签做文本内容跳转以及超链接的应用,CSS设计内容样式和图片、动画、视频的大小位置格式,JavaScript实现轮播图效果等。学习如何设计网页中的轮播图和动画效果,并掌握a标签文本内容跳转、超链接的应用、播放音乐与视频等操作。通过对Web知识内容的了解,我们掌握了HTML、CSS和JavaScript的基本知识以及利用它们实现一些简单的应用。1、使用Web知识实现一个简单的网页设计,利用HTML的a标签做文本内容跳转以及超链接的应用。_web前端网页设计代码