使用DITADoclet 和DITA API 规范生成DITA Java API 参考文档
目标
在本文中，学习如何使用DITADoclet、DITA Java API 规范和Eclipse IDE 创建多种格式的Java API 参考文档。DITADoclet 生成DITA Java API 文件，自动创建Java API 参考文档的DITAMAP 和MAPLIST 文件（DITA Java API 规范），从Java 源代码中直接提取开发人员注释，并把这些信息迁移到生成的DITA API 文件中。
常用缩写词
∙API：应用程序编程接口
∙CHM：编译的Windows® HTML 帮助
∙CSS：层叠样式表
∙DITA：Darwin Information Typing Architecture
∙DTD：文档类型定义
∙HTML：超文本标记语言
∙IDE：集成开发环境
∙J2EE：Java 2 平台，企业版
∙JDK：Java 开发工具箱
∙JSP：Java Server Pages
∙URI：统一资源标识符
∙XHTML：可扩展超文本标记语言
∙XML：可扩展标记语言
∙XSLT：可扩展样式表语言转换
通常情况下，使用Sun Microsystems 提供的Javadoc 工具从Java 源代码生成Java API 参考文档。Javadoc 能够生成Java API 参考文档的基本结构，但是文档常常不完整并对开发人员注释有限制。在开发团队发生变动时，往往倾向于把API 编写者和编辑完全排斥于Java API 参考文档过程之外。开发
人员只有时间管理Java 源代码和不完整的注释。显然，这种情况会给API 文档编写者和致力于生成高质量API 文档的其他人造成严重的困难。
API 编写者可以使用DITADoclet 和DITA Java API 解决方案提供的工具生成具有完整文档的Java API。具有完整文档的API 可以用于几个用途，但是最重要的用途是让API 用户能够全面了解、搜索和浏览可用的API 功能。为了完整地使用API 的功能，软件用户需要具有完整准确的文档的API。
java编译器ide最新版下载
为了解释DITADoclet 的工作方式，本文还要介绍Javadoc 标准doclet 解决方案使用的一些重要概念。为了让DITADoclet 自动提取过程能够有效地发挥作用，必须根据Javadoc 规则在Java 源代码中添加注释。否则，在用DITADoclet 提取注释时，就可能无法准确地处理注释，产生的API 可能是不完整的。本文讨论以下主题：
∙先决条件
∙什么是DITA Java API 规范？
∙DITADoclet 安装
∙使用Eclipse Javadoc Generation 向导（标准doclet）创建Javadoc 文档
∙使用以下方式创建Java API 参考文档：
o Eclipse Javadoc Generation 向导(DITADoclet)
o命令提示
∙DITADoclet 的优点和缺点
DITADoclet 的下载链接见参考资料。
可以通过 网站进一步了解DITA 以及如何创建或编辑DITA 文件，寻更多支持DITA 的XML 编辑器。强烈建议使用XML 编辑器以避免在标记中出现错误。有许多XML 编辑器：Arbortext Editor™、<oXygen/>® XML Editor、XMLBuddy™（一个Eclipse 插件）、Altova® XMLSpy®、 等等。我建议使用Arbortext Editor 作为内容发布系统。
目标读者
本文是为API 编写者撰写的。假设读者熟悉Java 软件、Java API 参考文档结构和Javadoc 生成，而且作为API 编写者希望进一步了解如何提供更好的Java API 参考文档。
API 编写者应该理解开发人员编写的代码，然后把相关信息提取到API 文档中。要想使用DITADoclet 成功地生成DITA Java API 文档，就必须熟悉Java 源代码
先决条件
本文解释从Java 源代码直接生成Java API 参考DITA 文件所需的先决条件，以及如何使用Eclipse 转换文件。在使用DITADoclet 和DITA Java API 规范之前，需要熟悉以下概念：
∙Java API 参考文档过程和Javadoc 生成
∙Eclipse
o Java IDE 和编辑器的透视图和视图
o Eclipse 基本概念，比如体系结构、插件和在工作台中插入插件
o插件的基本元素，比如项目、Eclipse 视图和编辑器
o如何使用Eclipse Java IDE 创建、安装和运行简单的插件
∙Eclipse 是基本IDE，但是有许多与Java 相关的Eclipse 插件，还有一些在Eclipse 上构建的商业IDE：
o Rational® Software Architect 是一个全面的集成开发环境，支持以图形化方式设计、构造、测试、分析和部署应用程序
o Rational Application Developer for WebSphere Software 用图形化开发特性扩展Eclipse
o IBM® WebSphere® Studio 是IBM 提供的一种强大的流行的J2EE IDE
o IBM WebSphere Studio Site Developer for Java 是一种用于Windows 和Linux 平台的Java IDE
o Sun Java Studio Creator
o JBuilder
这些产品的下载链接见参考资料。我建议使用Eclipse 构建工具或直接从命令提示行运行DITADoclet。
什么是DITA Java API 规范？
如果您熟悉DITA，那么可以跳过本节，跳到下面的 DITADoclet 安装。
DITA 致力于生成一致、完整且正确的技术文档。DITA API 规范是一个包含DITA 主题类型的包，用于生成Java API 文档文件。DITADoclet 从Java 源代码直接生成DITA 文件。可以从命令提示或通过使用Eclipse 运行它。
Darwin Information Typing Architecture (DITA)
Wikipedia 上列出的DITA 简史
∙2001 年3 月：IBM 引入DITA
∙2002 年5 月：在主题规范中添加域规范
∙2004 年4 月：成立OASIS Technical Committee for DITA
∙2005 年2 月：SourceForge 开始支持DITA Open Toolkit
∙2005 年6 月：批准DITA v1.0 成为OASIS 标准
∙2005 年8 月：发布DITA Open Toolkit v1.1
∙2006 年3 月：OASIS 启动
∙2007 年8 月：OASIS 批准DITA V1.1，包括Bookmap 规范
DITA 是一种开放的OASIS 标准和基于XML 的体系结构，用于编写、生成和交付技术文档。尽管可以在任何文本编辑器中编辑DITA 文件，但是在XML 编辑器中可以更轻松地插入和修改标记，并确保文件符合DITA DTD 和模式。建议使用XML 编辑器以避免在标记中出现错误。可用的XML 编辑器包括Ar
bortext Editor、oXygen、XML Buddy（一个Eclipse 插件）、Altova XML Spy 等等。
要想进一步了解DITA 以及如何创建或编辑DITA 文件，寻更多支持DITA 的XML 编辑器，可以通过参考资料中的链接访问DITA 组织网站。
DITA Open Platform 是免费的软件，可以根据Free Software Foundation 发布的条款重新发行和修改。发行DITA Open Platform 的原则是希望能够帮助用户，但是不提供任何保证。详情见参考资料。DITA API 规范
DITA API 规范文档描述基于XML 的DITA 体系结构，包括用于一般编程（所有编程语言）和Java 编程语言的DTD 元素。DITA API 规范包含用于为一般和Java API 生成参考文档的主题类型和元素。与每种语言相关的DITA API 规范由模块组成。模块是为特定的任务设计的主题类型，比如描述API 包或类。每个模块包含用来描述编程语言的特定部分的XML 元素。
在本文中，学习如何使用DITADoclet 生成DITA Java API 参考文件，并使用DITA Java API 解决方案创建参考文档。
可以使用DITA Generic API 规范为Java、Visual Basic 和其他编程语言编写和生成API 参考文档。DITADoclet 安装
要想运行DITADoclet，就需要安装Java Development Kit (JDK) 和Eclipse。
安装JDK
∙如果Java 二进制代码没有包含在系统路径中，或者没有定义JAVA_HOME 环境变量，就无法运行这个工具。运行DITADoclet 需要JDK。
∙推荐使用Java 5 JDK。通常情况下，Java 系统安装在与C:\Program Files\Java\jdk1.5.0_06\ 相似的路径中。要想查明系统上安装的Java 版本，可以在命令提示上输入以下命令：Java -version ∙如果您的Java 不是最近的版本，可以从Sun 下载站点下载JDK、J2RE 或JRE（见参考资料中的链接）。
安装Eclipse Classic
∙下载Eclipse Classic for Windows、IBM Rational Developer 或Rational Software Architect Standard Edition，把zip 文件解压到您选择的目录中（例如Windows 上的C:\eclipse\）。参
见参考资料中的链接。
∙最重要的一点是，在Windows 平台上必须确保Eclipse 安装路径不包含空格。关于不同工具的安装细节，请参考Eclipse 官方文档。要想检查是否已经安装了Javadoc 工具，可以打开命令提示并输入Java
doc。如果收到错误，就说明还没有安装Javadoc (jdk1.5.0_xx)，需要从Sun 网站下载jdk1.5.0_xx 并在Windows 路径中添加目录：C:\Program Files\Java\jdk1.5.0_xx。
安装DITADoclet
下载DITADoclet Tool zip 文件并把它解压到您选择的目录中（例如，Windows 上的C:\DITA\）。
这会创建\DITA 目录，其中包含、 和\demo 子目录。
o\demo 子目录包含\src 资源目录、选项和包。
o\src 资源目录包含用作示例的Java 源代码文件。可以从SourceForge 网站直接下载源代码文件(DITA-OT1.4_src.zip)。
安装org.dita.dost 插件
1. 到您的Eclipse 版本使用的工作空间目录。这个目录通常在\workspace 目录中，这是Eclipse
安装目录的一个子目录。如果要使用快捷方式或脚本启动Eclipse，它应该是快捷方式或脚本的
当前工作目录下面的子目录\workspace（例如，C:\eclipse\workspace）。
2. 下载org.dita.dost zip 文件并把它解压到Eclipse 工作空间目录中。这会创建Java 项目
org.dita.dost。
3. 把Java 项目org.dita.dost 导入Eclipse 工作空间。
可选的安装步骤
下面几步是可选的，我不打算在这里解释这些步骤。为了完成和测试DITA API 文件，需要把 .dita 文件转换为 .xhtml 文件。可以使用DITA Open Toolkit 转换DITA Java API 文件或从DITA API 文件生成输出。使用转换器需要安装apiref 和javaapiref 插件。
1. 可选：下载并安装DITA Open Toolkit。
2. 可选：下载并安装DITA Java API 规范（apiref-0.8 和avaapiref-0.8）。
使用标准doclet（Eclipse Javadoc Generation 向导）创建Javadoc 文档
为了了解DITADoclet 的基本作用和结构，有必要先简要讨论一下Javadoc 工具。JDK ??档提供对Javadoc 工具选项的详细描述。如果您熟悉Javadoc 工具，可以马上使用DITADoclet。Javadoc 工具（或DITADoclet）解析源代码文件、提取Javadoc 注释并构建文档数据的内部集合。
下面的步骤说明在Eclipse 开发环境中如何使用标准Javadoc doclet 生成Javadoc。
1. 在这个过程中，将使用Eclipse 插件org.dita.dost。
2. 在Eclipse 的Package Explorer 视图的左面板中，选择要为其生成Javadoc 的Java 源代码
（例如，使用Eclipse 插件org.dita.dost 的源代码）。右键单击org.dita.dost并在菜单中选
择Export。Export 窗口打开。
3. 选择Javadoc并单击Next。Generate Javadoc 窗口打开。
4. 在Javadoc Command框中，选择。 的路径通常是C:\Program
Files\Java\jdk1.5.0_06\（见图1）。
图1. 选择 路径
5. 在Generate Javadoc 窗口中，选择Javadoc 文件要导出到的包。这个列表由Eclipse 工作台
设置。只能选择一个项目，因为在运行Javadoc 工具时每次只能使用一个项目类路径。
6. 为了筛选包的成员，选择可见性（一般情况下选择Public）。
o选项包括：-package、-private、-protected 和-public，见图2。
图  2. 选择成员可见性
o
8. 单击Next指定其他Javadoc 生成选项。
9. 取消选择Overview，见图3。如果选择这个选项，Javadoc 会从指定的源代码文件获取概述文
档的文本，并把它放在Overview 页面（index.html）上。
图3. Overview 页面位置
10. 单击Next指定其他Javadoc 生成选项。
11. 指定要放在index.html 文件顶部的标题。如果不选择和指定文档标题，Javadoc 工具不会在
Overview 页面中添加它。
图4. 指定文档标题
其他Javadoc 选项
可能需要为Javadoc 工具指定更多的Javadoc 选项。这些选项采用VM 选项的形式，它们是用于控制Javadoc 工具的处理过程的系统选项。例如，设置-Xmx512m会给堆分配512 Mb 空间。
1. 为了加快Javadoc 过程的速度和关闭Javadoc 输出的信息性消息，我建议使用-quiet选项。
（提示：-verbose是另一个可以使用的选项。-verbose选项让编译器和Javadoc 输出关于正在

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。