dita文档

2009年12月11日修订说明：在“ 目标”和“ 安装org.dita.dost插件 ”标题下添加了两个指向可下载资源的链接。

2014年3月7日，修订说明：在参考资料中删除了过时的“ IBM XML认证”链接。

2014年3月17日修订说明：删除了参考资料中过时的“ DITA FAQ”链接。

目标

在本文中，您将学习如何使用DITADoclet，DITA Java API专业化和Eclipse IDE来创建Java API参考文档，以便于以多种格式轻松分发。 DITADoclet生成DITA Java API文件，自动为Java API参考文档创建DITAMAP和MAPLIST文件（DITA Java API专业化），从Java源代码中提取开发人员注释，并将信息迁移到生成的DITA API文件中。

通常，Sun Microsystems的Javadoc工具用于从Java源代码生成Java API参考文档。 Javadoc工具生成Java API参考文档的基本结构，但是该文档通常不完整，并且仅限于开发人员注释。 开发团队的变更似乎鼓励从Java API参考文档过程中完全删除API编写者和编辑者。 开发人员有时间只管理带有不完整注释的Java源代码文件。 这种情况清楚地向API编写者和其他对产生高质量API文档感兴趣的人提出了一些挑战。

DITADoclet和DITA Java API解决方案为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生成向导（DITADoclet）
  • 命令提示符
• DITADoclet的优缺点

请参阅可下载资源以下载DITADoclet。

要了解有关DITA的更多信息，如何创建或编辑DITA文件以及查找更多支持DITA的XML编辑器，请访问http://dita.xml.org网站。 我强烈建议您使用XML编辑器以避免标记错误。 提供了许多不同的XML编辑器：Arbortext Editor™，<oXygen />®XML编辑器，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生成
• 蚀
  • 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
  • 用于Java的IBM WebSphere Studio Site Developer是用于Windows和Linux的Java IDE
  • Sun Java Studio Creator
  • JBuilder的

要下载这些插件，请参阅参考资料 。 我建议使用Eclipse构建工具或直接从命令提示符行运行DITADoclet。

什么是DITA Java API专业化？

如果您熟悉DITA，则可以跳过此说明并转到下面的DITADoclet安装 。

DITA强制执行一致，完整和正确的技术文档。 DITA API专业化表示产生Java API文档文件的DITA主题类型的包。 DITADoclet直接从Java源代码生成DITA文件。 您可以从命令提示符或使用Eclipse运行它。

达尔文信息键入架构（DITA）

DITA代表一种开放的，OASIS标准，基于XML的体系结构，用于创作，生成和交付技术信息。 尽管您可以在任何文本编辑器中编辑DITA文件，但是XML编辑器使您可以轻松插入和修改标签，同时符合DITA DTD和模式。 我确实建议您使用XML编辑器来消除标记中的错误。 可用的XML编辑器包括Arbortext编辑器，oXygen，XML Buddy（Eclipse插件），Altova XML Spy等。

要了解更多关于DITA以及如何创建或编辑DITA文件，寻找更多的XML编辑器，支持DITA，请参阅链接到DITA组织网站相关主题 。

DITA开放平台是免费软件，您可以根据自由软件基金会发布的GNU通用公共许可的条款进行重新分发和修改。 发行DITA开放平台是希望它会有用，但没有任何保证。 请参阅相关主题的更多细节。

DITA API专业化

DITA API专业化文档通过用于通用（所有编程语言）和Java编程语言的DTD元素描述了基于XML的DITA架构。 DITA API专长包括主题类型和元素，用于记录通用和Java API参考。 每个特定于语言的DITA API专长都包含模块。 模块是为特定任务（例如描述API包或类）设计的主题类型。 每个模块都包含适当的XML元素，以描述编程语言的特定部分。

在本文中，您将学习如何运行DITADoclet来生成DITA Java API参考文件，以及如何使用DITA Java API解决方案来记录引用。

您可以使用DITA通用API专长来创作和生成Java，Visual Basic和其他编程语言的API参考文档。

DITADoclet安装

要运行DITADoclet，您需要安装Java开发工具包（JDK）和Eclipse。

安装JDK

• 如果系统路径中不包含Java二进制文件，或者未定义JAVA_HOME环境变量，则运行此工具可能会失败。 您需要JDK来运行DITADoclet。
• 建议使用Java 5 JDK。 通常，Java安装的路径类似于C：\ Program Files \ Java \ jdk1.5.0_06 \。 要确定系统上已安装的Java版本，请在命令提示符下键入： Java -version
• 如果您的Java版本不是最新，下载JDK，J2RE或JRE从Sun下载站点（请参阅相关信息的链接。）

安装Eclipse Classic

• 下载适用于Windows的Eclipse Classic，IBM Rational Developer或Rational Software Architect Standard Edition，然后将zip文件解压缩到您选择的目录中（例如，在Windows上为C：\ eclipse \）。 请参阅相关主题的链接。
• 最重要的是确保Eclipse安装路径在Windows平台上不包含任何空格。 有关不同工具安装的更多详细信息，请参考官方Eclipse文档。 要检查您是否安装了Javadoc工具，请打开命令提示符并键入Javadoc 。 如果收到错误，则说明您没有Javadoc（jdk1.5.0_xx），并且需要从Sun站点下载jdk1.5.0_xx，并将目录添加到Windows路径：C：\ Program Files \ Java \ jdk1.5.0_xx。

安装DITADoclet

• 下载DITADoclet工具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工作区目录中。 这将创建一个名为org.dita.dost的Java项目。
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创建Javadoc文档（Eclipse Javadoc生成向导）

要了解DITADoclet的基本角色和结构，简要回顾一下Javadoc工具非常有用。 JDK文档提供了Javadoc工具选项的详细说明。 如果您熟悉Javadoc工具，则可以立即使用DITADoclet。 Javadoc工具（或DITADoclet）解析源文件，提取Javadoc注释，并建立文档数据的内部集合。

以下步骤显示了如何使用标准Javadoc Doclet在Eclipse开发环境中生成Javadoc。

1. 您将使用Eclipse插件之一org.dita.dost来说明该过程。
2. 在Eclipse的Package Explorer视图的左窗格中，选择需要为其生成Javadoc的Java源代码（在本示例中，您使用Eclipse插件之一org.dita.dost。）右键单击在org.dita.dost上 ，然后从下拉列表中选择导出 。 将打开“导出”窗口。
3. 选择Javadoc ，然后单击下一步 。 将打开“生成Javadoc”窗口。
4. 在“ Javadoc命令：配置”窗口中，选择Javadoc.exe 。 通常，Javadoc.exe具有类似C：\ Program Files \ Java \ jdk1.5.0_06 \ bin \ Javadoc.exe的路径（请参见图1 ）。
   

   图1.选择javadoc.exe路径

   
5. 在“生成Javadoc”窗口中，选择要导出到Javadoc文件的软件包。 该列表由Eclipse工作台选择初始化。 您只能选择一个项目，因为在运行Javadoc工具时一次只能使用一个项目类路径。
6. 要过滤包的成员，请选择可见性（通常将选择Public 。）
   • 选择为： -package，-private，-protected或-public ， 如图2所示 。

     图2.选择成员可见性

     
   • 表1说明了根据所需可见性选择的成员。 -public选择最少的成员， -private选择最多的成员。

表1.成员可见性

1. 选择“ 使用标准Doclet”以标准doclet启动Javadoc命令（默认）。
   • 目标：选择标准doclet将生成的文档写入的目标。 目标是特定于doclet的标准参数，因此在使用自定义doclet时未启用。 标准doclet将写入的目标可以是例如工作空间子目录\ workspace \ doc.dita.dost \ output。
2. 单击“ 下一步”指定其他Javadoc生成选项。
3. 取消选择Overview ， 如图3所示 。 如果选中，则此选项指定Javadoc应该从指定的源文件中检索概述文档的文本，并将其放在“概述”页面（index.html）上。
   

   图3.概述页面位置

   
4. 单击“ 下一步”指定其他Javadoc生成选项。
5. 指定要放置在index.html文件顶部附近的标题。 如果未选择并指定文档标题，则Javadoc工具不会将其添加到“概述”页面。
   

   图4.指定文档标题

   

其他Javadoc选项

您可能需要添加更多Javadoc选项，以便Javadoc工具进行处理。 这些采用VM optioens的形式， VM optioens是用于控制Javadoc工具处理的系统选项。 例如，设置-Xmx512m将为堆分配512 Mb。

1. 为了加快JavaDoc的处理过程并关闭Javadoc中的所有参考消息，我建议使用-quiet选项来帮助创建Javadoc注释。 （提示： -verbose是您可以使用的另一个选项。- verbose选项使编译器和Javadoc打印出有关正在编译哪些源文件以及正在记录哪些类文件的消息。）

   图5.指定VM选项和Javadoc选项

   
2. doclet在工作空间子目录\ workspace \ org.dita.dost \ output \中为插件文档生成输出HTML文件，这是您的插件文档目录。
3. 单击完成以生成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生成向导（DITADoclet）创建Java API参考文档。

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

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通过使用标签来处理自定义块标签，而DITADoclet则不。

以下步骤显示了如何在Eclipse开发环境中将定制的doclet DITADoclet与Javadoc结合使用：

1. 在Eclipse的左窗格中，选择org.dita.dost ，您将为其生成Javadoc的源代码插件。
2. 右键单击所选插件，然后从下拉列表中选择“ 导出” 。 将打开“导出”窗口。
3. 选择Javadoc ，然后单击下一步 。 将打开“生成Javadoc”窗口。
   

   图6. Javadoc生成向导（Standard Doclet）打开了Generate Javadoc窗口

   
4. 在Javadoc命令字段中，指定DITADoclet.exe的路径。 安装DITADoclet时，它可能已安装在C：\ DITA \ DITADoclet.exe。
5. 在“ 生成Javadoc”窗口中，选择要导出到Javadoc文件的软件包。 该列表由Eclipse工作台初始化。 您只能选择一个项目，因为在运行Javadoc工具时一次只能使用一个项目类路径。 选择示例项目org.dida.dost 。
6. 由于此版本的DITA Java API专业化版本仅支持Java公共元素，因此请选择具有可见性Public的成员。
7. 选择“ 使用标准Doclet”以标准doclet启动Javadoc命令（默认）。
8. 指定标准doclet将生成的文档写入的目标位置。 （该目标是特定于doclet的标准参数，因此在使用自定义doclet时未启用。）标准doclet写入的目标可以是，例如，工作空间子目录，指定为.. \ workspace \ doc。 dita.dost \ topics 。
9. 对于“基本选项” ，单击“ 下一步 ”。
   

   图7. Javadoc生成向导（Standard Doclet）-选择基本的Javadoc选项

   
10. 在“ 文档标题”字段中，指定要放置在概述摘要文件顶部附近的标题。 如果省略文档标题，则DITADoclet将添加默认标题Building DITA output 。
11. 对于基本的Javadoc选项，请取消选择复选框， 如图7所示 。 这些是可用的选项以及DITADoclet如何处理它们：
    • 生成使用页面 ：DITADoclet不创建使用页面。
    • 生成层次结构树 ：DITADoclet将自动创建带有或不带有此标志选项输入的层次结构树页面。
    • 生成导航栏 ：DITADoclet将自动为每个页面创建导航栏，无论是否为此标志选项输入。
    • 生成索引 ：DITADoclet将自动创建带有或不带有此标志选项输入的索引页。
    • 每个字母单独的索引 ：DITADoclet不会为每个字母页面创建单独的索引。
12. 对于“ 记录这些标签”选项，取消选择复选框， 如图7所示 。
    • @author ：DITADoclet将自动将作者添加到元页面，无论此标志选项是否输入。
    • @version ：DITADoclet将自动将版本添加到.dita页面，无论是否为此标志选项输入。
    • @deprecated ：DITADoclet将自动将不推荐使用的信息添加到.dita页面，无论是否为此标志选项输入。
    • @不推荐使用的列表：DITADoclet将不会创建不推荐使用的列表页面。
13. 请记住，DITADoclet工具仅考虑“目标”字段值和“文档标题”选项。 在此示例中，Destination的值为.. \ workspace \ doc.dita.dost \ topics 。 文档标题的值为DITA-OT 。 如果没有为“目标”字段指定指定的值，则DITADoclet工具将在源代码文件夹（\ src）中创建所有.dita文件。 如果您未指定文档标题字段值，则DITADoclet工具将添加默认标题Building DITA output 。
14. 此时，您尚未创建overview.html文件，因此请不要选中Overview复选框。 （当第二次运行该工具时，可以从\ workspace \ src文件夹中选择新生成的overview.html文件。）
    

    图8.不指定概述页面路径

    
15. 单击“ 下一步 ”获得Extra Javadoc选项（带空格的路径名必须用引号引起来）。 这些选项是可选的。
    

    图9.额外的javadoc选项

    
    • -贡献者将作者文本包含在生成的DITA中
    • -provider指定插件提供程序名称的详细信息。
    • -debug在Javadoc控制台中提供警告消息
16. 选项-contributor和-provider将向所有DITA生成的文件添加一个序言部分，其中包含编写者的名称，贡献者的名称，提供者的名称，生成的日期，等等。 请参见下面的示例。
    • 创建者作者<author type="creator">Lian, Li</author>来自源代码@author javadoc标记。
    • 贡献者的作者<author type="contributor">Mariana Alupului</author>来自-contributor Javadoc选项， 如图9所示 。

    清单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. 单击“ 完成”以生成DITA API文档。

其他警告

DITADoclet显示所有警告，这些警告可能会帮助您检测Eclipse控制台中的文档中的错误或遗漏（请参见图10 ）。 默认情况下不打印这些警告。 要请求它们，请使用选项-debug 。

图10. Javadoc控制台以及示例消息和警告

当日志文件达到一定大小时，您可以自动保存它们。 在控制台中，单击Ctrl-Break以获取此输出。 这在执行-debug选项场景中特别有用，因此您可以查看Eclipse系统中文档生成过程中发生的情况。 您还可以将日志文件发送给开发人员，以帮助他们了解哪些源文件缺少信息，警告等。

DITADoclet导航文件

DITADoclet会为插件生成输出DITA（XML）文件，并在org.dita.dost \ topics \文件夹中生成其他几个导航文件。 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参考的名称以及描述该软件包或一组软件包及其组件所必需的所有元素。

图11. DITA输出-org.dita.dost.ditamap文件

org.dita.dost.doc.reltable.ditamap

reltable文件定义关系表以管理内部类和接口。 如果没有内部类或接口，则DITADoclet将不会创建reltable。

org.dita.dost.doc.ditaval

您可以通过以下属性来过滤DITA的DITA元素：受众群体，平台，产品和其他属性。 您可以在DITA源中的元素上为这些属性中的一个或多个指定值。 使用这些属性，您可以打开或关闭文本。 也就是说，根据您声明的属性隐藏文本或显示文本。 如果您不使用文件中的属性值，则可以从ditaval文件中完全删除该属性。 如果您使用文件中的值，但现在不想标记它，请将操作从标志更改为包含在ditaval文件中（请参见图12 ）。

图12. DITA输出-org.dita.dost.doc.ditaval文件中的Properties选项卡

org.dita.dost.doc.maplist

映射列表允许您包括ditamap和reltable.ditamap文件。 地图列表的作用类似于主文件，并调用地图列表，而地图列表又称为DITA主题。

图13. DITA输出-org.dita.dost.doc.maplist文件

层次结构文件

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

• 树
• allnames.dita
• allclasses.dita

Java API参考页面包含每个视图的链接：

图14. Java API Reference页面上指向层次结构和索引页面的链接

查看三个文件及其内容。

树

tree.dita文件中的Class Hierarchy页面（ 图15 ）包含一个类列表和一个接口列表（对于所有软件包）。 这些类是从Java.lang.Object开始的继承结构组织的。

图15. tree.dita文件中的类层次结构

allnames.dita

allnames.dita文件中的Index （ 图16 ）包含所有类，接口，构造函数，方法和字段的字母列表。

图16. allnames.dita文件中的索引

allclasses.dita

allclasses.dita文件中的类和接口索引 （ 图17 ）包含所有类和接口的字母列表。

图17. allclasses.dita文件中的类/接口索引

您不需要编辑tree.dita，allnames.dita或allclasses.dita文件。 仅在运行变压器时出现错误或警告时才编辑它们。

DITA输出中的辅助文件

javastyle.fos是DITADoclet创建的辅助文件，可以与Epic Editor一起使用。 该文件为编写者提供了Java源代码中缺少的信息的直观表示，编写者可以在其中直接在DITA Java API文件或Java源代码中输入缺少的信息。

如果使用Epic编辑生成的DITA文件，则可以直接利用Java源代码利用DITADoclet（fos文件）生成的绿色突出显示的文本。 它以绿色突出显示缺少的注释，并提供了可能的文档替代方法。 图18显示了使用DITADoclet生成并在Epic Editor中打开的DITA文件。

图18. DITADoclet生成的fos文件中的示例输出

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

清单2. overview.html

<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>

图19.带评论草案的summary.dita概述

第二次运行DITADoclet时，您已经生成了Overview（概述）（overview.html）。 现在，您可以指定DITADoclet应该从overview.html文件中检索此页面的文本。 DITADoclet将所有信息（开发人员评论）复制到overview-summary.dita文件中。

再次运行DITADoclet时，输出文件将如图20所示 。

图20. Overview-summary.dita（不带评论草案）

您可以编辑overview.html文件，也可以直接在overview-summary.dita文件中进行编辑。 在记录文件时，为避免再次运行DITADoclet时覆盖此信息，请右键单击overview-summary.dita文件。 选择“ 属性” ，然后为“属性”选择“ 只读” 。

首次运行DITADoclet工具时，该工具将创建package.html和package-summary.dita文件。 如果Java源代码中不存在该工具，则该工具将生成package.html文件。 有关package-summary.dita文件生成的模板的示例，请参见图21 。 （为防止DITADoclet覆盖package-summary.dita信息，请在package-summary.dita文件上单击鼠标右键。选择“ 属性” ，然后为“属性”选择“ 只读” 。这将锁定文件内容。）

图21.第一次运行DITADoclet工具后的package-summary.dita

第二次运行DITADoclet工具时，您的Java源代码中已经存在package.html文件，该工具将从该文件中获取所有信息并将其迁移到package-summary.dita文件。 现在，您可以在这些文件中完成软件包的信息。 有关示例，请参见图22 。

图22.第二次运行DITADoclet工具后的package-summary.dita

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

请参见图23中的示例，以获取已记录的软件包，您可以在浏览器中查看它：

图23.浏览器中显示的文档

DITADoclet records all output files into the root output directory specified with the -d command option, and into subdirectories of the root output directory. DITADoclet automatically creates the root output directory and all of the subdirectories. Figure 24 shows the directory structure and the names of the default files created by the DITADoclet using an example of the directory structure generated for your sample package, org.dita.dost. The left side shows the Java source code and its component files. In the right side, you can see the DITA files generated from this Java source code folder.

Figure 24. Directory structure and names of default files

When you run the DITADoclet tool for the first time, the tool creates all DITA files. After that, it will create a copy of the initially generated DITA files as #0.xxx.dita, #1.xxx.dita, and so on until you reach #64.

Keeping different versions of the files can help during the debugging and verification process of the documentation after changes to Javadoc comments are made in Java source code.

Creating Java API reference documentation using DITADoclet and command prompt line

It is important to know what parameters Javadoc reads and uses, and the parameters that DITADoclet reads and uses. If you run Javadoc -help , you will see that the Javadoc tool has two sets of command-line options. One set is generic and will work with any doclet. The second set of options is specific to the standard doclet. Options in this second set will not be available when you use custom doclets. Your custom doclets can also define their own command prompt line options. This documentation contains only detailed descriptions of all options provided for DITADoclet. A detailed description of the Javadoc tool options is provided with the JDK documentation.

DITADoclet release 1.1.3 (see Related topics for a link) provides a command line interface as an alternative so users with little knowledge of Eclipse can easily use the toolkit.

Running Javadoc for the org.dita.dost example

1. See if Javadoc is installed on your path. Typically, Javadoc will have a path like C:\Program Files\Java\jdk1.5.0_06\bin.
2. Use the @options option to place the options in a separate file (documentation for this is provided with the JDK.)
3. Use the @packages option to place the packages' fully qualified names in a separate file.
4. Run the following command from your DITA directory C:\DITA\>: Javadoc @options @packages

Figure 25. Options and packages using the example

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

Running DITADoclet for the org.dita.dost example

Running DITADoclet from the command prompt is the same as running Javadoc:

1. If you add DITADoclet.exe to your path, use the @packages option to place the packages' fully qualified names in a separate file, and use the @options option to put the options in a file, you can run the following command from your directory C:\DITA\: DITADoclet @options @packages
2. If you choose to type the entire command in the command line, it will look something like this:

   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

Using the DITADoclet for your project

• You can modify the @options and @packages files by opening them with the WordPad editor.
• Run the command: DITADoclet.exe @options @packages .

Running DITA-OT transformer to generate XHTML files from DITA

With the DITADoclet presented in this article, you produce Java API reference help documentation based on DITA files and a small number of additional documentation elements. Using DITADoclet, it is easy to create Eclipse platform documentation, which can then be used to produce XML and XHTML output formats for the existing Eclipse help systems. Over time, you can expect the addition of more output formats.

DITA-OT transformer has the capability to generate HTMLHelp (CHM). See Figures 26 and 27 for screen captures of DITA-OT transformer examples of CHM files, the first with draft comments, and the second without.

Figure 26. CHM with draft comments

Figure 27. CHM without draft comments

The API writer needs to resolve all draft comments (see Figure 26 ). A complete and fully documented set of Java API reference documentation will not contain any draft comments highlighted in green (see Figure 27 ).

API writers can use the DITADoclet testing solution to identify the missing information from the Java source code, and also test their work for complete and fully documented reference files before they deliver the source code to the online Help.

You can run the DITA-OT transformer to generate XHTML files from the DITA Java API files in an Eclipse environment. The example in Figure 28 was generated in this fashion.

Figure 28. Eclipse on-line help

DITADoclet advantages

The advantages of using the DITADoclet to generate DITA Java API documentation are:

搜索

Provides an efficient way to retrieve methods and classes/or interfaces. The Javadoc system does not provide such a search mechanism for the table of contents (TOC).

Navigation

Provides a TOC navigation that is generated automatically directly from the Java source code.

指数

The indexes complement the keyword search. Indexes are created by the API writer and can therefore give valuable additional information.
The index lists all packages, classes, interfaces, methods and fields, sets them into context (for example, gives the containing class for a method or field) and links to the document describing the entry.

Links

DITA shows the missing links that are hard to find without using DITA. For this demo project (org.dita.dost), you have 108 topics with 3567 local links that DITA automatically checks.

DITADoclet disadvantages

You can use the tool to create DITA Java API files only from Java source files version 1.4. The next version of DITA API specialization and DITADoclet will support Java version 1.5 and 1.6 (including annotations, enumeration, generics, and so on.)

Specialization contributors

I want to acknowledge and extend a special thanks to all the key people that contributed to the development of the DITA API specialization:

• Type architect: Michael Priestley - Senior Technical Staff Member (STSM) Lead IBM DITA Architect
• Document structures and processing: Erik Hennum - XML, DITA, XSLT, Perl; Web technologies: JSP, Java Servlet, JavaScript, CSS; User Assistance: Eclipse, JavaHelp
• Subject matter experts: Mariana Alupului
• Information developers: Mariana Alupului, Rob Pierce, Nigel Hopper, Dennis Grace, Ian Hartshorn
• Information architect: Erik Hennum
• Authoring Tools (Information Development Workbench): Robert D Anderson
• Translation Tool Development and Globalization Support: David Walters
• Java API pilot project lead: Mariana Alupului
• Editor: Michelle C Carey
• IDWBWIN Help and Guidelines Documentation: Mariana Alupului
• Guidelines and standards (style guidelines for output): Michelle C Carey

翻译自: https://www.ibm.com/developerworks/xml/library/x-DITAdoclet/index.html

dita文档