使用 DITADoclet 和 DITA API 规范生成 DITA Java API 参考文档

文档选项 未显示需要 JavaScript 的文档选项 英文原文

级别： 中级

Mariana Alupului, 信息开发人员, Rational 软件, IBM

2009 年 3 月 09 日

DITADoclet 从 Java 源代码中直接提取开发人员注释并生成一套完整的 DITA Java™ API 参考文件。这可以节省时间和确保生成高质量的 API 文档。学习如何使用 DITADoclet 生成 DITA Java 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。

为了解释 DITADoclet 的工作方式，本文还要介绍 Javadoc 标准 doclet 解决方案使用的一些重要概念。为了让 DITADoclet 自动提取过程能够有效地发挥作用，必须根据 Javadoc 规则在 Java 源代码中添加注释。否则，在用 DITADoclet 提取注释时，就可能无法准确地处理注释，产生的 API 可能是不完整的。

本文讨论以下主题：

• 先决条件
• 什么是 DITA Java API 规范？
• DITADoclet 安装
• 使用 Eclipse Javadoc Generation 向导（标准 doclet）创建 Javadoc 文档
• 使用以下方式创建 Java API 参考文档：
• Eclipse Javadoc Generation 向导 (DITADoclet)
• 命令提示
• DITADoclet 的优点和缺点

DITADoclet 的下载链接见 参考资料。

可以通过 http://dita.xml.org 网站进一步了解 DITA 以及如何创建或编辑 DITA 文件，寻找更多支持 DITA 的 XML 编辑器。强烈建议使用 XML 编辑器以避免在标记中出现错误。有许多 XML 编辑器：Arbortext Editor™、<oXygen/>® XML Editor、XMLBuddy™（一个 Eclipse 插件）、Altova® XMLSpy®、OpenOffice.org 等等。我建议使用 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
• Java IDE 和编辑器的透视图和视图
• Eclipse 基本概念，比如体系结构、插件和在工作台中插入插件
• 插件的基本元素，比如项目、Eclipse 视图和编辑器
• 如何使用 Eclipse Java IDE 创建、安装和运行简单的插件
• Eclipse 是基本 IDE，但是有许多与 Java 相关的 Eclipse 插件，还有一些在 Eclipse 上构建的商业 IDE：
• Rational® Software Architect 是一个全面的集成开发环境，支持以图形化方式设计、构造、测试、分析和部署应用程序
• Rational Application Developer for WebSphere Software 用图形化开发特性扩展 Eclipse
• IBM® WebSphere® Studio 是 IBM 提供的一种强大的流行的 J2EE IDE
• IBM WebSphere Studio Site Developer for Java 是一种用于 Windows 和 Linux 平台的 Java IDE
• Sun Java Studio Creator
• 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 启动 DITA.XML.org 2007 年 8 月：OASIS 批准 DITA V1.1，包括 Bookmap 规范

DITA 是一种开放的 OASIS 标准和基于 XML 的体系结构，用于编写、生成和交付技术文档。尽管可以在任何文本编辑器中编辑 DITA 文件，但是在 XML 编辑器中可以更轻松地插入和修改标记，并确保文件符合 DITA DTD 和模式。建议使用 XML 编辑器以避免在标记中出现错误。可用的 XML 编辑器包括 Arbortext 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 工具，可以打开命令提示并输入 Javadoc。如果收到错误，就说明还没有安装 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 目录，其中包含 DITADoclet.exe、ReadeMe.txt 和 \demo 子目录。
• \demo 子目录包含 \src 资源目录、选项和包。
• \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 框中，选择 Javadoc.exe。Javadoc.exe 的路径通常是 C:\Program Files\Java\jdk1.5.0_06\bin\Javadoc.exe（见 图 1）。
   
   图 1. 选择 javadoc.exe 路径
   
   
   
5. 在 Generate Javadoc 窗口中，选择 Javadoc 文件要导出到的包。这个列表由 Eclipse 工作台设置。只能选择一个项目，因为在运行 Javadoc 工具时每次只能使用一个项目类路径。
6. 为了筛选包的成员，选择可见性（一般情况下选择 Public）。
   • 选项包括：-package、-private、-protected 和 -public，见 图 2。
     
     图 2. 选择成员可见性
     
     
     
   • 表 1 说明可见性与选择的成员的关系。-public 选择的成员数量最少，-private 选择的成员数量最多。

7. 选择 Use Standard Doclet，用标准 doclet 启动 Javadoc 命令（默认）。
• 目标：选择一个目标目录，标准 doclet 将把生成的文档写到这个目录中。目标是标准 doclet 特有的参数，因此在使用定制的 doclet 时不使用这个参数。标准 doclet 将写到的目标可以是工作空间子目录 \workspace\doc.dita.dost\output。
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 输出关于正在编译的源代码文件和正在生成文档的类文件的消息） 。
   
   图 5. 指定 VM 选项和 Javadoc 选项
   
   
   
2. doclet 在工作空间子目录 \workspace\org.dita.dost\output\（插件文档目录）中生成插件文档的输出 HTML 文件。
3. 单击 Finish 生成 Javadoc 文档。可以使用控制台视图观察生成 Javadoc 的进度。

Javadoc 从 Java 源代码文件获取它的所有信息和文本，但是有两个例外：概述文本文件和针对每个包的文本文件。它们是可选的。Javadoc 创建的文件分别是 index.html 和 package-summary.html。在使用标准 Javadoc 时，生成的概述和包文件是没有任何信息的 HTML 文件。包文档向开发人员提供使用包所需的信息。包信息有助于理解包中组件的协作方式，可能包含代码、原型、结构图表、设计模式、代码编写标准等等。如果选择在浏览器中打开索引文件的选项，那么在生成 Javadoc 之后，会在默认的 Web 浏览器中打开 Javadoc 生成的 index.html 页面。

讨论了 Javadoc 如何生成 Java API 参考文件之后，现在看看 DITADoclet 如何为 Java API 参考文档生成 DITA 文件。在下一节中，讨论如何使用 Eclipse Javadoc Generation 向导（DITADoclet）创建 Java API 参考文档。

使用 DITADoclet（Eclipse Javadoc Generation 向导）创建 Java API 参考文档

DITADoclet 解析源代码文件、提取 Javadoc 注释并从 Java API 源代码文件直接构建 DITA 文件。这种设计的目的是为 API 技术编写者提供方便，他们只需要利用现有的 Eclipse Javadoc Generation 向导知识，再学习很少一些与 DITA 文档相关的差异：

• DITADoclet 生成的文档的总体结构与标准 doclet 生成的文档相同。
• DITADoclet 支持标准 doclet 提供的所有选项，但是只考虑以下选项：-sourcepath、-d、-doctitle、-overview 和 -public。
• DITADoclet 还支持另外几个选项：-contributor、-provider、-debug 和 -nocomment。
• 标准 doclet 使用 taglet 处理定制的块标记，而 DITADoclet 不这么做。

下面的步骤讲解在 Eclipse 开发环境中如何结合使用定制的 doclet DITADoclet 和 Javadoc：

1. 在 Eclipse 中的左面板中选择 org.dita.dost，我们将为这个插件的源代码生成 Javadoc。
2. 右键单击选择的插件，在下拉菜单中选择 Export。Export 窗口打开。
3. 选择 Javadoc 并单击 Next。Generate Javadoc 窗口打开。
   
   图 6. Javadoc Generation 向导（标准 doclet），Generate Javadoc 窗口打开
   
   
   
4. 在 Javadoc command 框中，输入 DITADoclet.exe 的路径。DITADoclet 可能安装在 C:\DITA\DITADoclet.exe。
5. 在 Generate Javadoc 窗口中，选择 Javadoc 文件要导出到的包。这个列表由 Eclipse 工作台设置。只能选择一个项目，因为在运行 Javadoc 工具时每次只能使用一个项目类路径。选择示例项目 org.dida.dost。
6. 因为这个版本的 DITA Java API 规范只支持 Java 公共元素，所以选择成员可见性 Public。
7. 选择 Use Standard Doclet，用标准 doclet 启动 Javadoc 命令（默认）。
8. 指定一个目标，标准 doclet 将把生成的文档写到这个目录中。（目标是标准 doclet 特有的参数，因此在使用定制的 doclet 时不使用这个参数）。标准 doclet 将写到的目标可以是工作空间子目录 ..\workspace\doc.dita.dost\topics。
9. 单击 Next 选择基本选项。
   
   图 7. Javadoc Generation 向导（标准 doclet）—— 选择基本 Javadoc 选项
   
   
   
10. 在 Document title 框中，指定要放在概述文件顶部的标题。如果忽略文档标题，DITADoclet 将添加默认标题 Building DITA output。
11. 对于基本 Javadoc 选项，按照 图 7 取消选择复选框。下面是可用的选项和 DITADoclet 处理它们的方式：
• Generate use page：DITADoclet 不创建使用页面。
• Generate hierarchy tree：无论是否选择这个选项，DITADoclet 都会自动创建层次结构树页面。
• Generate navigation bar：无论是否选择这个选项，DITADoclet 都会为每个页面自动创建导航条。
• Generate index：无论是否选择这个选项，DITADoclet 都会自动创建索引页面。
• Separate index per letter：DITADoclet 不为每个字母页面创建单独的索引。
12. 对于 Document these tags 选项，按照 图 7 取消选择复选框。
• @author：无论是否选择这个选项，DITADoclet 都会在元页面中自动添加作者。
• @version：无论是否选择这个选项，DITADoclet 都会在 .dita 页面中自动添加版本。
• @deprecated：无论是否选择这个选项，DITADoclet 都会在 .dita 页面中自动添加已废弃信息。
• @deprecated list：DITADoclet 不创建废弃列表页面。
13. 请记住，DITADoclet 只考虑 Destination 的值和 Document title 选项。在这个示例中，Destination 的值是 ..\workspace\doc.dita.dost\topics。Document title 的值是 DITA-OT。如果没有指定 Destination 的值，DITADoclet 工具将在源代码文件夹（\src）中创建所有 .dita 文件。如果没有指定 Document title 的值，DITADoclet 工具将添加默认标题 Building DITA output。
14. 现在还没有创建 overview.html 文件，所以不选择 Overview 复选框。（在第二次运行此工具时，可以从 \workspace\src 文件夹中选择刚生成的 overview.html 文件） 。
    
    图 8. 不指定概述页面路径
    
    
    
15. 单击 Next，选择额外的 Javadoc 选项。这些选项是可以任意选择的。
    
    图 9. 额外的 Javadoc 选项
    
    
    
• -contributor 在生成的 DITA 中包含编写者文本
• -provider 指定详细的插件提供者名称
• -debug 向 Javadoc 控制台提供警告消息
16. -contributor 和 -provider 选项在生成的所有 DITA 文件中添加一个序言部分，其中包含编写者的姓名、贡献者的姓名、提供者的名称、生成日期等等。下面是一个示例。
    • 创建者 <author type="creator">Lian, Li</author> 来自源代码中的 @author javadoc 标记。
    • 贡献者 <author type="contributor">Mariana Alupului</author> 来自 图 9 中的 -contributor Javadoc 选项。
    
    
    清单 1. 输出的 <prolog>
    

    <prolog> <author type="creator">Lian, Li</author> <author type="contributor">Mariana Alupului</author> <source href="org/dita/dost/xxx.Java">org/dita/dost/test/xxx.Java</source> <publisher>IBM</publisher> <copyright type="primary"> <copyryear year="2008"/> <copyrholder>IBM</copyrholder> </copyright> <critdates> <created date="Wed, 17-Dec-2008 12:20:16 EST"/> <revised modified="Fri, 19-Dec-2008 15:49:48 EST" status="new"/> </critdates> </prolog>

    
    
17. 单击 Finish 生成 DITA API 文档。

额外的警告

DITADoclet 可以在 Eclipse 控制台中显示所有警告消息，帮助用户判断文档中的错误或缺少的内容（见 图 10）。在默认情况下并不输出这些警告消息。可以使用 -debug 选项启用警告消息。

可以在日志文件达到特定的大小时自动保存它们。在控制台中，单击 Ctrl-Break 获得这个输出。这在执行 -debug 选项时尤其有意义，让我们能够看到在生成文档的过程中发生的情况。还可以把日志文件发送给开发人员，帮助他们了解哪些源代码文件中缺少信息或有错误。

回页首

DITADoclet 导航文件

DITADoclet 在 org.dita.dost\topics\ 文件夹中生成插件的输出 DITA (XML) 文件和另外几个导航文件。DITADoclet 生成的导航文件是：

• org.dita.dost.ditamap
• org.dita.dost.doc.reltable.ditamap
• org.dita.dost.doc.ditaval
• org.dita.dost.doc.maplist

org.dita.dost.ditamap

ditamap 文件提供 Java API Reference 的名称以及描述包及其组件所需的所有元素。

org.dita.dost.doc.reltable.ditamap

reltable 文件定义用来管理内部类和接口的关系表。如果没有内部类或接口，DITADoclet 就不创建 reltable 文件。

org.dita.dost.doc.ditaval

可以根据 audience、platform、product 等属性筛选 ditaval DITA 元素。在 DITA 源代码中的元素中，指定这些属性的值。通过使用这些属性，可以打开或关闭文本；也就是说，根据声明的属性显示文本或隐藏文本。如果在文件中不使用属性值，那么可以从 ditaval 文件中完全删除属性。如果在文件中使用属性值，但是不希望现在就设置它，那么在 ditaval 文件中把 Action 由 flag 改为 include（见 图 12）。

org.dita.dost.doc.maplist

maplist 可以包含一个 ditamap 和一个 reltable.ditamap 文件。映射列表作为主文件，它调用一系列映射，映射进而调用 DITA 主题。

层次结构文件

DITADoclet 生成三个层次结构文件，它们描述类层次结构、类和接口列表以及类、接口、构造函数、方法和字段的索引：

• tree.dita
• allnames.dita
• allclasses.dita

下面看看这三个文件的内容。

tree.dita

tree.dita 文件中的类层次结构页面（图 15）包含（所有包中的）类和接口的列表。类按照继承结构组织成树结构，起点是 Java.lang.Object。

allnames.dita

allnames.dita 文件中的索引页面（图 16）包含所有类、接口、构造函数、方法和字段的列表，列表按照字母表次序排序。

allclasses.dita

allclasses.dita 文件中的类和接口索引页面（图 17）包含所有类和接口的列表，列表按照字母表次序排序。

不需要编辑 tree.dita、allnames.dita 或 allclasses.dita 文件。只有在运行转换器时遇到错误或警告的情况下，才应该编辑它们。

DITA 输出中的辅助文件

javastyle.fos 是 DITADoclet 生成的辅助文件，Epic Editor 可以使用它。这个文件向编写者指出 Java 源代码中缺少的信息，编写者可以在这里把缺少的信息直接输入 DITA Java API 文件或 Java 源代码。

如果使用 Epic 编辑生成的 DITA 文件，可以看到以绿色突出显示的文本，这是 DITADoclet（fos 文件）直接从 Java 源代码生成的。它以绿色突出显示缺少的注释并提供可能的替换文本。图 18 显示一个由 DITADoclet 生成的 DITA 文件在 Epic Editor 中的输出情况。

在首次运行 DITADoclet 时，此工具会创建 overview.html 文件（清单 2）并把它保存在工作空间子目录 /workspace/org.dita.dost/src 中。它还创建 overview-summary.dita 文件（图 19）并把它保存在子目录 /workspace/org.dita.dost/topics 中。

				
<html>
 <head>
  <title>Building DITA output</title>
<heading  refname="" type="major" back-to-top="no">Headings</heading>
 </head>
 <body>
  Overview short description added in source code src\overview.html template.
  <h2>Overview Specification</h2>
  Overview specification added in source code src\overview.html template.
 </body>
</html>

在第二次运行 DITADoclet 时，已经生成了概述（overview.html）。现在，可以让 DITADoclet 从 overview.html 文件获取此页面的文本。DITADoclet 将把所有信息（开发人员注释）复制到 overview-summary.dita 文件中。

再次运行 DITADoclet 时，输出文件与 图 20 相似。

可以编辑 overview.html 文件，也可以直接编辑 overview-summary.dita 文件。为了避免在再次运行 DITADoclet 时覆盖这些信息，右键单击 overview-summary.dita 文件。选择 Properties 并为 Attributes 选择 Read-only。

在首次运行 DITADoclet 工具时，此工具会创建 package.html 和 package-summary.dita 文件。如果 Java 源代码中没有 package.html 文件，工具会生成这个文件。为 package-summary.dita 文件生成的模板示例见 图 21。（为了防止 DITADoclet 覆盖 package-summary.dita 信息，右键单击 package-summary.dita 文件。选择 Properties 并为 Attributes 选择 Read-only。这会锁定文件内容）。

在第二次运行 DITADoclet 时，Java 源代码中已经有 package.html 文件，工具会把这个文件中的所有信息复制到 package-summary.dita 文件中。现在可以在这些文件中完成包信息。图 22 给出一个示例。

现在可以为包选择一个模板（在首次运行工具时生成的 package.html 文件），DITADoclet 将自动地获取这个页面的开发人员注释，并把所有信息复制到 package-summary.dita 文件中。

图 23 是在浏览器中显示的包文档示例：

DITADoclet 把所有输出文件放在 -d 命令选项指定的输出根目录及其子目录中。DITADoclet 自动创建输出根目录及所有子目录。图 24 显示 DITADoclet 为示例包 org.dita.dost 创建的目录结构和默认文件的名称。左边是 Java 源代码及其组件文件。在右边，可以看到根据这个 Java 源代码文件夹生成的 DITA 文件。

在首次运行 DITADoclet 工具时，此工具会创建所有 DITA 文件。在此之后，它会创建最初生成的 DITA 文件的拷贝并命名为 #0.xxx.dita、#1.xxx.dita 等等，直到编号到达 #64。

保留文件的不同版本有助于在 Java 源代码中修改 Javadoc 注释之后调试和检验文档。

使用 DITADoclet 和命令提示行创建 Java API 参考文档

一定要了解 Javadoc 读取和使用的参数以及 DITADoclet 读取和使用的参数。如果运行 Javadoc -help，会看到 Javadoc 工具有两组命令行选项。其中一组是通用选项，适用于任何 doclet。第二组选项专门针对标准 doclet。在使用定制的 doclet 时，不能使用第二组中的选项。定制的 doclet 也可以定义自己的命令提示行选项。本文只详细描述 DITADoclet 提供的所有选项。对 Javadoc 工具选项的详细描述见 JDK 文档。

DITADoclet 1.1.3（见 参考资料 中的链接）提供一个命令行界面，让不太熟悉 Eclipse 的用户也能够轻松地使用这个工具集。

针对 org.dita.dost 示例运行 Javadoc

1. 检查路径上是否安装了 Javadoc。Javadoc 的路径通常是 C:\Program Files\Java\jdk1.5.0_06\bin。
2. 使用 @options 选项把选项放在一个单独的文件中（此选项的文档见 JDK）。
3. 使用 @packages 选项把包的完全限定名放在一个单独的文件中。
4. 在 DITA 目录 C:\DITA\ 中运行以下命令：Javadoc @options @packages。

C:\\DITA\>Javadoc 
@options @packages

C:\\DITA\>DITADoclet.exe 
@options @packages

-sourcepath demo/src
-d demo/output/org.dita.dost.doc
-overview demo/src/overview-summary.html
-doctitle 'Building DITA output'
-use
-tree
-navbar
-index
-noauthor
-version
-deprecated
-public

-sourcepath demo/src
-d demo/dita/org.dita.dost.doc
-overview demo/src/overview-summary.html
-doctitle 'Building DITA output'
-provider IBM 
-contributor "Mariana Alupului"
-public

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

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

针对 org.dita.dost 示例运行 DITADoclet

从命令提示运行 DITADoclet 的方法与运行 Javadoc 相同：

1. 在路径中添加 DITADoclet.exe，使用 @packages 选项把包的完全限定名放在一个单独的文件中，使用 @options 选项把选项放在一个文件中，然后可以在目录 C:\DITA\ 中运行以下命令：DITADoclet @options @packages
2. 如果要在命令行上输入完整的命令，命令会像下面这样：

   DITADoclet.exe -sourcepath demo/src -d demo/output/org.dita.dost.doc -overview demo/src/overview -summary.html -doctitle 'Building DITA output' -provider IBM -contributor "Mariana Alupului" 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 org.dita.dost.pipeline org.dita.dost.platform org.dita.dost.reader org.dita.dost.util org.dita.dost.writer org.dita.dost.exception

   
   

针对自己的项目使用 DITADoclet

• 可以在 WordPad 编辑器中打开并修改 @options 和 @packages 文件。
• 运行命令：DITADoclet.exe @options @packages。

通过运行 DITA-OT 转换器根据 DITA 生成 XHTML 文件

通过使用 DITADoclet，可以根据 DITA 文件和其他一些文档元素生成 Java API 参考帮助文档。很容易创建 Eclipse 平台文档，然后使用这些文档生成适合现有 Eclipse 帮助系统的 XML 和 XHTML 输出文档。以后会增加更多的输出格式。

DITA-OT 转换器能够生成 HTMLHelp（CHM）。图 26 和 图 27 给出 DITA-OT 转换器生成的两个 CHM 文件示例，第一个包含注释草稿，第二个不包含。

API 编写者需要解决所有注释草稿（见 图 26）。完成后的 Java API 文档不包含以绿色突出显示的任何注释草稿（见 图 27）。

API 编写者可以使用 DITADoclet 测试解决方案查明 Java 源代码中缺少的信息，还可以在把源代码交付给联机帮助之前测试参考文档的效果。

可以在 Eclipse 环境中运行 DITA-OT 转换器，根据 DITA Java API 文件生成 XHTML 文件。图 28 给出以这种方式生成的一个示例。

DITADoclet 的优点

使用 DITADoclet 生成 DITA Java API 文档的优点是：

搜索

能够高效地搜索方法、类和接口。Javadoc 系统没有提供类似的内容目录搜索机制。

导航

提供从 Java 源代码直接自动生成的内容目录导航。

索引

索引补充关键字搜索。索引是由 API 编写者创建的，因此可以提供有价值的额外信息。
索引列出所有包、类、接口、方法和字段，并提供上下文（例如，包含一个方法或字段的类）和描述它们的文档的链接。

链接

DITA 显示缺少的链接；如果不使用 DITA，很难发现它们。对于示例项目（org.dita.dost），DITA 自动检查 108 个主题和 3567 个本地链接。

DITADoclet 的缺点

只能使用此工具从 Java 1.4 源代码文件创建 DITA Java API 文件。DITA API 规范和 DITADoclet 的下一个版本将支持 Java 1.5 和 1.6（包括注解、枚举、泛型等等）。

对规范做出贡献的人员

我想感谢对 DITA API 规范的开发做出重要贡献的所有人：

• 类型架构师：Michael Priestley - 高级技术人员 (STSM) IBM DITA 架构师负责人
• 文档结构和处理：Erik Hennum - XML、DITA、XSLT、Perl；Web 技术：JSP、Java Servlet、JavaScript、CSS；用户帮助：Eclipse、JavaHelp
• 主题问题专家：Mariana Alupului
• 信息开发人员：Mariana Alupului、Rob Pierce、Nigel Hopper、Dennis Grace、Ian Hartshorn
• 信息架构师：Erik Hennum
• 编写工具（Information Development Workbench）：Robert D Anderson
• 翻译工具开发和全球化支持：David Walters
• Java API 试验项目负责人：Mariana Alupului
• 编辑：Michelle C Carey
• IDWBWIN 帮助和指导方针文档：Mariana Alupului
• 指导方针和标准（输出的风格指导方针）：Michelle C Carey

回页首

下载

	关于下载方法的信息

参考资料

• 您可以参阅本文在 developerWorks 全球网站上的 英文原文。
  
  
• 阅读这些关于 DITA 的 developerWorks 文章：
  • 从 HTML 迁移到 DITA，第 1 部分: 从 HTML 转到 DITA 的简单步骤（Robert Anderson，Don Day，Erik Hennum；developerWorks，2005 年 1 月）：使用现有的 HTML 主题快速掌握 DITA。使用一个 XSLT 转换迁移信息并学习如何保证结果质量。
  • 从 HTML 迁移到 DITA，第 2 部分：扩展迁移工具得到更加理想的结果（Robert Anderson，developerWorks，2005 年 2 月）：了解关于迁移的更详细信息，学习如何得到更加理想的结果。
  • Darwin 信息类型化体系结构简介（Don Day，Michael Priestley，David Schell；2003 年 10 月）：了解 DITA 的路线图：什么是 DITA 以及如何把它应用于技术文档。
  • 专门化 DITA 主题类型（Michael Priestley，2003 年 10 月）：创建新的基于主题的文档类型，以便很容易地组合到不同交付上下文中。
  • The DITA FAQ（Don Day，Michael Priestley，Gretchen Hargis；2004 年 11 月）：了解提示和技术以及常见 DITA 问题的答案。
  • Specializing domains in DITA（Erik Hennum，2005 年 9 月更新）：通过灵活地扩展和重用信息类型来扩展基本 DTD。
  
  
• Eclipse 平台：随时关注 Eclipse 的技术进展、新闻、插件和社区。还可以通过以下文章扩展 Eclipse 技能。
  • 使用 Eclipse 帮助系统为项目编制文档 -- 构建易于使用且可搜索的帮助文档（Arthur Barr，developerWorks，2004 年 1 月）：构建易用且可搜索的帮助文档。
  • 精通 Eclipse V3.4 系列（Prashant Deva，developerWorks，2008 年 10 月到 11 月，2009 年 1 月）：这个分三部分的文章系列讨论 Eclipse IDE 工作台的优缺点、JDT 以及关于 JDT 文本编辑器的提示和技巧。学完这个系列之后，您就可以成为高级用户。
  
  
• DITA Open Toolkit：这是用于 DITA DTD 和模式的 OASIS DITA Technical Committee 规范的实现。这个工具集可以把 DITA 内容（映射和主题）转换为可交付格式。
  • Java API Reference Specialization：这个插件提供为 Java 类库编写文档的基础。
  
  
• IBM XML 认证：了解如何成为 IBM 认证的 XML 和相关技术开发人员。
  
  
• XML 技术库：developerWorks XML 专区提供了大量技术文章和技巧、教程、标准以及 IBM Redbook。
  
  
• developerWorks 技术活动和网络广播：通过这些活动了解技术的最新发展。
  
  
• developerWorks podcasts：收听适合于软件开发人员的有趣的访谈和讨论。

• Rational Software Architect：这是一个全面的集成开发环境，支持以图形化方式设计、构造、测试、分析和部署应用程序。
  
  
• Rational Application Developer for WebSphere Software：用图形化开发特性扩展 Eclipse。
  
  
• IBM WebSphere Studio：这是 IBM 提供的一种强大的流行的 J2EE IDE。
  
  
• IBM WebSphere Studio Site Developer for Java 是一种用于 Windows 和 Linux 平台的 Java IDE。
  
  
• DITA organization site：进一步了解 DITA 以及如何创建或编辑 DITA 文件，寻找更多支持 DITA 的 XML 编辑器。
  
  
• Java EE 5 JDK：这个工具集通过更简单的编程模型简化应用程序开发，提高生产力。
  
  
• Eclipse Classic for Windows：这是一个基本的开发工具。
  
  
• IBM Rational Developer：这是一个用于开发传统 IBM 应用程序的完整的开发环境。
  
  
• DITA Toolkit 源代码文件 (DITA-OT1.4_src.zip)：从 SourceForge 网站直接下载 DITA Toolkit 的源代码文件。
  
  
• DITA Open Toolkit：下载这个工具集并使用它把 DITA 内容（映射和主题）转换为可交付格式。
  
  
• GNU General Public License：可以根据 Free Software Foundation 发布的这些条款，重新发行和修改免费的 DITA Open Platform 软件。
  
  
• DITA Java API Specialization apiref-0.8：下载并使用这个插件。
  
  
• DITA Java API Specialization Javaapiref-0.8：下载并使用这个插件。
  
  
• IBM 产品评估试用软件：使用可直接从 developerWorks 下载的 IBM 试用软件构建您的下一个项目，包括来自 DB2®、Lotus®、Rational®、Tivoli® 和 WebSphere® 的应用程序开发工具和中间件产品。
  
  

• XML 专区论坛：参与各个以 XML 为中心的论坛。
  
  
• 参与 developerWorks blogs 并加入 developerWorks 社区。
  
  

关于作者

		Mariana Alupului 是 IBM Software Group，Rational Software 的高级技术文档编制人员（API）。除了编写文档并领导软件程序设计环境中的 Java、VB、C++ 的 API 文档项目，她还是开发用于书写 API 库的语言一致的参考文档的 Darwin Information Typing Architecture (DITA) XML 规范的 IBM 公司团队的一名成员。Mariana 帮助创建 API 参考风格指导，并且是 corporate ID-Support Council 和 ID Technical Writers Council 的成员。她是 Society for Technical Communication 的一员，并且出席了 2005 年的“Beyond the Bleeding Edge”会议。

对本文的评价

太差！ (1) 需提高 (2) 一般；尚可 (3) 好文章 (4) 真棒！(5) 建议？

回页首