Generate DITA Java API reference documentation using DITADoclet and DITA API specialization

Automatically create reference documentation from Java source with DITA API specialization

DITADoclet extracts developer comments and generates a complete set of DITA Java™ API reference files directly from the Java source code. Save time and still produce quality API documentation. Learn to run DITADoclet to generate the DITA Java API reference files, and use DITA Java API solution to document the references.

Share:

Mariana Alupului (malupulu@us.ibm.com), Information Developer, IBM

Photo of Mariana AlupuluiMariana Alupului is an Information Developer for IBM Rational Software. In addition to documenting and leading API documentation projects for Java, VB, C++, in software programming environment, she is a member of the IBM Corporation team that developed the Darwin Information Typing Architecture (DITA) XML specialization for writing language-conformant reference documentation for API libraries. Mariana developed DITADoclet to complete Java DITA API specialization. Mariana is the lead of the corporate Java API guidelines workgroup and a member of the corporate ID Technical Writers Council. She has presented Java DITA API solution at the Society for Technical Communication (STC) "Beyond the Bleeding Edge" session (2005) and DITA/TechComm Conference (2008).

You can reach Mariana at malupulu@us.ibm.com



17 March 2014 (First published 03 February 2009)

Also available in Japanese

11 Dec 2009 Revision note: Added two links to Downloads under the headings Objectives and Install the org.dita.dost plugin.

07 Mar 2014 Revision note: Removed obsolete "IBM XML certification" link in Resources.

17 Mar 2014 Revision note: Removed obsolete "DITA FAQ" link in Resources.

Objectives

In this article, you will learn how to use DITADoclet, DITA Java API specialization, and the Eclipse IDE to create Java API reference documentation for easy distribution in many formats. DITADoclet generates the DITA Java API files, automatically creates the DITAMAP and MAPLIST files (DITA Java API specialization) for the Java API reference documentation, extracts the developer comments from the Java source code, and migrates the information to the generated DITA API files.

Frequently used acronyms

  • API: Application programming interface
  • CHM: Compiled Windows® HTML Help
  • CSS: Cascading stylesheets
  • DITA: Darwin Information Typing Architecture
  • DTD: Document type definition
  • HTML: Hypertext Markup Language
  • IDE: Integrated development environment
  • J2EE: Java 2 Platform, Enterprise Edition
  • JDK: Java Development Kit
  • JSP: Java Server Pages
  • URI: Uniform Resource Identifier
  • XHTML: Extensible Hypertext Markup Language
  • XML: Extensible Markup Language
  • XSLT: Extensible Stylesheet Language Transformation

Typically, the Javadoc tool from Sun Microsystems is used to generate Java API reference documentation from Java source code. The Javadoc tool generates the basic structure for the Java API reference documentation, but the documentation is often incomplete and limited to developer comments. Changes to development teams appear to encourage removal of the API writers and editors from the Java API reference documentation process altogether. Developers have time to manage only Java source code files with incomplete comments. This situation clearly presents API writers and others who are interested in producing high quality API documentation with some substantial challenges.

The DITADoclet and DITA Java API solution provides API writers with the tools to generate fully documented Java APIs. A fully documented API can serve several purposes, but the most important reason is to allow the API users to fully understand, search, and browse the API functions that are available to them. To completely use the functionality of the API, software users require an accurate and fully documented API.

To understand how DITADoclet works, the article also presents some of the important notions the Javadoc standard doclet solution uses. For the DITADoclet automatic extraction to work effectively, the Java source code must be documented according to Javadoc strict guidelines. Otherwise, when you extract the comments with the DITADoclet, it might not process them properly or the resulting API documentation might be incomplete.

This article presents the following:

  • Prerequisites
  • What is DITA Java API specialization?
  • DITADoclet installation
  • Creating Javadoc documentation using the Eclipse Javadoc Generation wizard (Standard Doclet)
  • Creating Java API reference documentation using:
    • Eclipse Javadoc Generation Wizard (DITADoclet)
    • Command prompt
  • DITADoclet advantages and disadvantages

See Downloads to download DITADoclet.

To learn more about DITA, how to create or edit DITA files, and find more XML editors that support DITA, see the http://dita.xml.org Web site. I highly recommend that you use an XML editor to avoid errors in tagging. Many different XML editors are available: Arbortext Editor™, <oXygen/>® XML Editor, XMLBuddy™ (an Eclipse plugin), Altova® XMLSpy®, OpenOffice.org, and more. I recommend using the Arbortext Editor as a content publishing system.

Audience

This material is for API writers and assumes that you are familiar with Java software, Java API references documentation structure, Javadoc generation, and, as an API writer, want to know more about how you can provide improved Java API references documentation.

The API writers are expected to understand the code written by developers and extract the relevant information to be published in the API documentation. The success you will achieve in using DITADoclet to generate DITA Java API documentation is based on your familiarity with Java source code.

Prerequisites

This article explains the prerequisites you need to generate Java API reference DITA files directly from Java source code, and how to transform the files using Eclipse. Before using DITADoclet and DITA Java API specialization, you need to be familiar with following concepts:

  • Java API reference documentation processes and Javadoc generation
  • Eclipse
    • The perspectives and views of the Java IDEs and editors
    • Eclipse basic concepts, such as architecture, plugins, and plugging into the workbench
    • The elements of a minimal plug-in, such as projects, Eclipse views, and editors
    • How to create, install, and run a simple plug-in using the Eclipse Java IDE
  • Eclipse is the base IDE, but there are many Java-related plugins for Eclipse, and several commercial IDEs built on top of Eclipse:
    • Rational® Software Architect is a comprehensive integrated development environment for visually designing, constructing, testing, profiling and deploying applications
    • Rational Application Developer for WebSphere Software extends Eclipse with visual development features
    • IBM® WebSphere® Studio is a powerful and popular J2EE IDE from IBM
    • IBM WebSphere Studio Site Developer for Java is a Java IDE for Windows and Linux
    • Sun Java Studio Creator
    • JBuilder

To download these plug-ins, see Resources. I recommend running DITADoclet either using the Eclipse build tool or directly from a command prompt line.

What is DITA Java API specialization?

If you are familiar with DITA, you can skip this explanation and go to DITADoclet installation below.

DITA enforces consistent, complete, and correct technical documentation. DITA API specialization represents a package of DITA topic types to produce Java API documentation files. DITADoclet generates the DITA files directly from the Java source code. You can run it from a command prompt or by using Eclipse.

The Darwin Information Typing Architecture (DITA)

Brief history of DITA as noted on Wikipedia

  • March, 2001: DITA introduced by IBM
  • May, 2002: Domain specialization added to topic specialization
  • April, 2004: OASIS Technical Committee for DITA formed
  • February, 2005: SourceForge begins DITA Open Toolkit support
  • June, 2005: DITA v1.0 is approved as an OASIS standard
  • August, 2005: DITA Open Toolkit v1.1 is released
  • March, 2006: OASIS launches DITA.XML.org
  • August, 2007: DITA V1.1 is approved by OASIS, including Bookmap specialization

DITA represents an open, OASIS standard, XML-based architecture for authoring, producing, and delivering technical information. While you can edit DITA files in any text editor, XML editors allow you to insert and modify tags easily while conforming to the DITA DTD and schemas. I do recommend that you use an XML editor to void errors in tagging. Available XML editors include Arbortext Editor, oXygen, XML Buddy (an Eclipse plugin), Altova XML Spy, and others.

To learn more about DITA, how to create or edit DITA files, and find more XML editors that support DITA, see the link to the DITA organization site in Resources.

The DITA Open Platform is free software that you can redistribute and modify under the terms of the GNU General Public License as published by the Free Software Foundation. The DITA Open Platform is distributed in the hope that it will be useful, but without any warranty. See Resources for more details.

DITA API specialization

The DITA API specialization documentation describes the XML-based DITA architecture through the DTD elements for generic (all programming languages) and Java programming language. The DITA API specialization includes topic types and elements for documenting generic and Java API references. Each language-specific DITA API specialization consists of modules. A module is a topic type designed for a specific task such as describing an API package or class. Each module includes the appropriate XML elements to describe a specific part of the programming language.

In this article, you learn how to run DITADoclet to generate the DITA Java API reference files, and use DITA Java API solution to document the references.

You can use the DITA Generic API specialization to author and generate API reference documentation for the Java, Visual Basic, and other programming languages.

DITADoclet installation

To run DITADoclet, you need to install the Java Development Kit (JDK) and Eclipse.

Install the JDK

  • Running this tool might fail if the Java binaries are not contained in the system path or if the JAVA_HOME environment variable is not defined. You need the JDK to run DITADoclet.
  • A Java 5 JDK is recommended. Typically, a Java installation will have a path similar to C:\Program Files\Java\jdk1.5.0_06\. To determine which Java version you have installed on your system, type at the command prompt: Java -version
  • If your Java version is not recent, download the JDK, J2RE, or JRE from the Sun download site (see Resources for the link.)

Install Eclipse Classic

  • Download Eclipse Classic for Windows, or IBM Rational Developer, or Rational Software Architect Standard Edition, and unzip the zip file into a directory of your choice (for example, C:\eclipse\ on Windows). See Resources for the links.
  • The most important thing is to be sure that the Eclipse installation path will not contain any spaces on the Windows platform. For more details on the different tools installations, please refer to the official Eclipse documentation. To check whether you have the Javadoc tool installed, open a command prompt and type Javadoc. If you receive an error, you do not have Javadoc (jdk1.5.0_xx), and you need to download jdk1.5.0_xx, from the Sun site, and add the directory to your Windows path: C:\Program Files\Java\jdk1.5.0_xx.

Install DITADoclet

  • Download the DITADoclet Tool zip file and unzip it into a directory of your choice (for example, C:\DITA\ on Windows). It will create a directory \DITA containing DITADoclet.exe, ReadeMe.txt, and a \demo subdirectory.
    • The \demo subdirectory contains the \src resources directory, the options, and packages.
    • The \src resources directory contains the Java source files which you will use as an example. You can download the source files (DITA-OT1.4_src.zip) directly from the SourceForge Web site.

Install the org.dita.dost plugin

  1. Find the workspace directory used by your version of Eclipse. Typically this is located inside the directory called \workspace, where you installed Eclipse in a subdirectory. If you are using a shortcut or script to launch Eclipse, then it will be under the current working directory of that shortcut or script in a subdirectory called \workspace (for example, C:\eclipse\workspace).
  2. Download the org.dita.dost zip file (see Downloads)and unzip it into the Eclipse workspace directory. This will create a Java project named org.dita.dost.
  3. Import the Java project org.dita.dost into your Eclipse workspace.

Optional installation steps

The next steps are optional and it is not my intention to explain these steps here. To complete and test your DITA API files, you need to transform .dita files to .xhtml files. You can use DITA Open Toolkit to transform the DITA Java API files or generate output from DITA API files. You need to install both apiref and javaapiref plugins for the transformer to work.

  1. Optional: Download and install the DITA Open Toolkit.
  2. Optional: Download and install DITA Java API specialization (apiref-0.8 and avaapiref-0.8).

Creating Javadoc documentation using Standard Doclet (Eclipse Javadoc Generation wizard)

To understand the basic role and structure of DITADoclet, it is useful to briefly review the Javadoc tool. A detailed description of the Javadoc tool options is provided with the JDK documentation. If you are familiar with the Javadoc tool, you can use DITADoclet right away. The Javadoc tool (or DITADoclet) parses the source files, extracts the Javadoc comments, and builds an internal collection of the documentation data.

The following steps show how to generate Javadoc in an Eclipse development environment using the Standard Javadoc Doclet.

  1. You will use one of the Eclipse plug-ins, org.dita.dost, to illustrate the process.
  2. In Eclipse, on the left pane in the Package Explorer view, select the Java source code for which Javadoc needs to be generated (for this example, you use one of the Eclipse plug-ins, org.dita.dost.) Right-click on org.dita.dost, and select Export from the drop-down list. The Export window opens.
  3. Select Javadoc and click Next. The Generate Javadoc window opens.
  4. In the Javadoc Command: configuration window select Javadoc.exe. Typically, Javadoc.exe will have a path like C:\Program Files\Java\jdk1.5.0_06\bin\Javadoc.exe (see Figure 1).
    Figure 1. Select javadoc.exe path
    Select the Javadoc.exe path
  5. In the Generate Javadoc window, select the packages that you want to export to the Javadoc files. This list is initialized by the Eclipse workbench selection. You can select only one project as you can use only one project classpath at a time when running the Javadoc tool.
  6. To filter the members of the package, select the visibility (you will normally select Public.)
    • The choices are: -package, -private, -protected, or -public as in Figure 2.
      Figure 2. Select the member visibility
      Select the member visibility
    • Table 1 illustrates which members to select according to the visibility you want. -public chooses the fewest, and -private chooses the greatest number of members.
Table 1. Member visibility
OptionDocuments these classes
-publicpublic...
-protectedpublicprotected..
-packagepublicprotected(package).
-privatepublicprotected(package)private
  1. Select Use Standard Doclet to start the Javadoc command with the standard doclet (default).
    • Destination: Select the destination to which the standard doclet will write the generated documentation. The destination is a standard doclet-specific argument, and therefore not enabled when using a custom doclet. The destination to which the standard doclet will write can be, for example, the workspace subdirectory \workspace\doc.dita.dost\output.
  2. Click Next to specify additional Javadoc generation options.
  3. Deselect Overview as in Figure 3. If selected, this option specifies that Javadoc should retrieve the text for the overview documentation from the source file specified and place it on the Overview page (index.html).
    Figure 3. Overview page location
    overview selection
  4. Click Next to specify additional Javadoc generation options.
  5. Specify the title to be placed near the top of the index.html file. If you do not select and specify the document title, the Javadoc tool will not add it to the Overview page.
    Figure 4. Specify the document title
    document title

You might need to add more Javadoc options for the Javadoc tool to process. These take the form of VM optioens, system options used to control the Javadoc tool processing. For example, setting -Xmx512m will allocate 512 Mb for the heap.

  1. To speed the JavaDoc process and turn off any informational messages from the Javadoc, I suggest using the -quiet option to help create the Javadoc comments. (Hint: -verbose is another option that you can use. The -verbose option causes the compiler and Javadoc to print out messages about which source files are being compiled and what class files are being documented.)
    Figure 5. Specify VM options and Javadoc options
    VM and Javadoc options
  2. The doclet generates the output HTML files for the plug-in documentation in the workspace subdirectory \workspace\org.dita.dost\output\, which is your plug-in documentation directory.
  3. Click Finish to generate the Javadoc documentation. You watch the progress of the JavaDoc generation using the console view.

Javadoc obtains all its information and text from the Java source files with two exceptions: an overview text file and a text file for each package. Both exceptions are optional. The files created by Javadoc are index.html and package-summary.html respectively. When you use the standard Javadoc, the generated overview and package files are HTML files without any information. The package documentation provides developers with the necessary information about using the packages. The package information is useful in understanding how things work together and might include code, prototype, structure chart diagrams, design patterns, coding standards, and so on. If you select the option of opening the index file in a browser, then after generation of Javadoc, you will find the Javadoc page index.html opened in your default Web Browser.

Now that you have reviewed how Javadoc generates the Java API reference files, look at how similarly DITADoclet generates DITA files for Java API reference documentation. In the next section, you'll see how to create Java API reference documentation using the Eclipse Javadoc Generation Wizard (DITADoclet).

Creating Java API reference documentation using DITADoclet (Eclipse Javadoc Generation Wizard)

DITADoclet parses the source files, extracts the Javadoc comments, and builds DITA files directly from Java API source code files. The goal of this design is to make it easy for API technical writers to leverage their existing Eclipse Javadoc Generation wizard knowledge and to only have to learn a very small set of DITA documentation-specific differences:

  • DITADoclet generates the documentation with the same overall structure as the documentation generated by the Standard Doclet.
  • DITADoclet supports all options provided by the Standard Doclet, but considers only these options: -sourcepath, -d, -doctitle, -overview, and -public.
  • DITADoclet also supports several additional options that you can use: -contributor, -provider, -debug, and -nocomment.
  • The standard doclet processes custom block tags by using taglets, while DITADoclet does not.

The following steps show how to use the customized doclet, DITADoclet, in combination with Javadoc in an Eclipse development environment:

  1. In Eclipse, on the left pane, select org.dita.dost, the source code plug-in for which you will generate Javadoc.
  2. Right-click on the selected plug-in, and, from the drop down list select Export. The Export window opens.
  3. Select Javadoc and click Next. The Generate Javadoc window opens.
    Figure 6. Javadoc generation wizard (Standard Doclet) with Generate Javadoc window open
    Javadoc generation wizard (Standard Doclet) with Generate Javadoc window open
  4. In the Javadoc command field, specify the path to DITADoclet.exe. When you installed DITADoclet, it was probably installed at C:\DITA\DITADoclet.exe.
  5. In the Generate Javadoc window select the packages that you want to export to the Javadoc file. This list is initialized by the Eclipse workbench. You can select only one project as you can use only one project classpath at a time when you run the Javadoc tool. Select the example project, org.dida.dost.
  6. Since this version of DITA Java API specialization supports only Java public elements, select members with visibility Public.
  7. Select Use Standard Doclet to start the Javadoc command with the standard doclet (default).
  8. Specify the destination to which the standard doclet will write the generated documentation. (The destination is a standard doclet-specific argument, and therefore not enabled when using a custom doclet.) The destination to which the standard doclet will write can be, for example, the workspace subdirectory, specified as ..\workspace\doc.dita.dost\topics.
  9. Click Next for the Basic Options.
    Figure 7. Javadoc generation wizard (Standard Doclet) - select basic Javadoc options
    Javadoc generation wizard (Standard Doclet) - select basic Javadoc options
  10. In the Document title field, specify the title to place near the top of the overview summary file. If you omit the document title, DITADoclet will add a default title, Building DITA output.
  11. For the basic Javadoc options, deselect the check boxes as in Figure 7. These are the options available and how DITADoclet processes them:
    • Generate use page: The DITADoclet does not create the use page.
    • Generate hierarchy tree: The DITADoclet will automatically create the hierarchy tree page with or without input for this flag option.
    • Generate navigation bar: The DITADoclet will automatically create the navigation bar for every page with or without input for this flag option.
    • Generate index: The DITADoclet will automatically create the index page with or without input for this flag option.
    • Separate index per letter: The DITADoclet will not create separate index per letter pages.
  12. For the Document these tags options, deselect the check boxes as in Figure 7.
    • @author: The DITADoclet will automatically add the author to the meta page with or without input for this flag option.
    • @version: The DITADoclet will automatically add the version to the .dita page with or without input for this flag option.
    • @deprecated: The DITADoclet will automatically add the deprecated information to the .dita page with or without input for this flag option.
    • @deprecated list: The DITADoclet will not create a deprecated list page.
  13. Keep in mind that the DITADoclet tool takes into consideration only the Destination field value and the Document title options. In this example, the value for Destination is ..\workspace\doc.dita.dost\topics. The value for the Document title is DITA-OT. Without a specified value for the Destination field, the DITADoclet tool will create all .dita files in your source code folder (\src). If you do not specify the Document title field value, the DITADoclet Tool will add a default title Building DITA output.
  14. At this point you have not created an overview.html file, so do not select the Overview check box. (When you run the tool for the second time, you can select the newly generated overview.html file from your \workspace\src folder.)
    Figure 8. Do not specify the overview page path
    overview page path
  15. Click Next for the Extra Javadoc options (path names with white spaces must be enclosed in quotes). These options are elective.
    Figure 9. Extra javadoc options
    Extra javadoc options
    • -contributor includes the writer text in the generated DITA
    • -provider specifies the plugin provider name details.
    • -debug provides warning messages in the Javadoc Console
  16. The options -contributor and -provider add a prolog section to all DITA generated files that contains the name of the writer, the name of the contributor, the provider name, the date of generation, and so on. See the example below.
    • The creator author <author type="creator">Lian, Li</author> comes from source code @author javadoc tags.
    • The contributor author <author type="contributor">Mariana Alupului</author> comes from the -contributor Javadoc option as in Figure 9.
    Listing 1. Output <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. Click Finish to generate the DITA API documentation.

Additional warnings

DITADoclet displays all warnings that might help you detect errors or omissions in your documentation in the Eclipse Console (see Figure 10). These warnings are not printed by default. To request them, use the option -debug.

Figure 10. Javadoc console with example messages and warnings
Javadoc console with example messages and warnings

You can automatically save log files when they reach a certain size. In the console, click Ctrl-Break to get this output. This is useful especially in executing -debug option scenarios, so you can see what happens within the generation of the documentation in the Eclipse system. You can also send the log files to developers to help them understand which source files have missing information, warnings, and so on.


DITADoclet navigation files

DITADoclet generates the output DITA (XML) files for the plug-in, and several other navigation files in the org.dita.dost\topics\ folder. The navigation files created by the DITADoclet are:

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

org.dita.dost.ditamap

The ditamap file provides the name of the Java API Reference and all the elements necessary to describe the package, or set of packages, and its components.

Figure 11. DITA output - the org.dita.dost.ditamap file
DITA output - the org.dita.dost.ditamap file

org.dita.dost.doc.reltable.ditamap

The reltable file defines relationship tables to manage inner classes and interfaces. DITADoclet will not create the reltable if there are no inner classes or interfaces.

org.dita.dost.doc.ditaval

You can filter the ditaval DITA elements by these attributes: audience, platform, product, and other properties. You specify a value for one or more of these attributes on the elements in your DITA source. With these properties, you can turn text on or off; that is, hide text or show text based on the properties that you declared. If you do not use the attribute values in your file, you can remove the attribute entirely from your ditaval file. If you use the values in your files, but do not want to flag it right now, change the action from flag to include in your ditaval file (see Figure 12).

Figure 12. DITA output - the Properties tab in the org.dita.dost.doc.ditaval file
DITA output - the Properties tab in the org.dita.dost.doc.ditaval file

org.dita.dost.doc.maplist

The maplist allows you to include a ditamap and a reltable.ditamap file. The map list acts like a master file and calls a list of maps which in turn call the DITA topics.

Figure 13. DITA output - the org.dita.dost.doc.maplist file
DITA output - the org.dita.dost.doc.maplist file

Hierarchy files

DITADoclet generates three files that describe the class hierarchy, a list of classes and interfaces, and an index of classes, interfaces, constructors, methods, and fields.

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

The Java API Reference page contains links to each view:

Figure 14. Links to hierarchy and index pages on the Java API Reference page
Links to hierarchy and index pages on the Java API Reference page

Look at the three files and their contents.

tree.dita

The Class Hierarchy page (Figure 15) in the tree.dita file contains a list of classes and a list of interfaces (for all packages). The classes are organized by inheritance structure starting with Java.lang.Object.

Figure 15. Class Hierarchy in the tree.dita file
Class Hierarchy in the tree.dita file

allnames.dita

The Index (Figure 16) in the allnames.dita file contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.

Figure 16. Index in the allnames.dita file
Index in the allnames.dita file

allclasses.dita

The Class and Interface Index (Figure 17) in the allclasses.dita file contains an alphabetic list of all classes and interfaces.

Figure 17. Class/Interface Index in the allclasses.dita file
Class Interface Index in the allclasses.dita file

You do not need to edit the tree.dita, allnames.dita, or allclasses.dita files. Edit them only if you have errors or warnings when you run the transformer.

Auxiliary files in the DITA output

javastyle.fos is an auxiliary file created by DITADoclet which can be used with Epic Editor. The file provides the writer with a visual representation of information that is missing from the Java source code and where the writer can enter the missing information directly in DITA Java API files or Java source code.

If you use Epic to edit the generated DITA files, you can take advantage of the green highlighted text generated by the DITADoclet (fos file) directly from the Java source code. It highlights, in green, the missing comments and provides a possible documentation alternative. Figure 18 shows a DITA file generated with DITADoclet and opened in Epic Editor.

Figure 18. Sample output in a fos file generated by DITADoclet
Sample output in a fos file generated by DITADoclet

When you run the DITADoclet for the first time, the tool creates the overview.html file (Listing 2) and saves it in the workspace subdirectory /workspace/org.dita.dost/src. It also creates the overview-summary.dita file (Figure 19), and saves it in the subdirectory /workspace/org.dita.dost/topics.

Listing 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>
Figure 19. Overview of summary.dita with draft comment
Overview of summary.dita with draft comment

When you run DITADoclet for the second time, you have already generated the Overview (overview.html). Now you can specify that DITADoclet should retrieve the text for this page from the overview.html file. DITADoclet will copy all the information (developer comments) to the overview-summary.dita file.

When you run the DITADoclet again, the output file will look like Figure 20.

Figure 20. Overview-summary.dita without draft comment
Overview of summary.dita without draft comment

You can edit the overview.html file, or you can edit directly in the overview-summary.dita file. When you document the file, to avoid overriding this information when you run DITADoclet again, right-click on the overview-summary.dita file. Select Properties, and for the Attributes, select Read-only.

When you first run the DITADoclet tool, the tool will create the package.html and package-summary.dita file. The tool generates the package.html file if the file is not present in Java source code. See Figure 21 for an example of the generated template for the package-summary.dita file. (To prevent the DITADoclet from overriding the package-summary.dita information, right-click on the package-summary.dita file. Select Properties and, for the Attributes, select Read-only. This will lock the file content.)

Figure 21. package-summary.dita after first run of DITADoclet tool
package-summary.dita after first run of DITADoclet tool

When you run the DITADoclet tool the second time, the package.html file is already present in your Java source code, and the tool will take all the information from this file and migrate it to package-summary.dita file. Now you can complete the information for the package in these files. See Figure 22 for an example.

Figure 22. package-summary.dita after second run of DITADoclet tool
package-summary.dita after second run of DITADoclet tool

You can now select a template for the package (the package.html file that is generated when you first run the tool), and DITADoclet will automatically retrieve the developer comments for this page and copy all the information to the package-summary.dita file.

See the example in Figure 23 for a documented package as you might view it in a browser:

Figure 23. Document as seen in a browser

[Short description]
The main package org.dita.dost.log contains the class DITAOTBuildLogger which is responsible to log messages both on the screen and into the log file.
Detailed description:
The messages on the screen present user with the status information, warning, error, and fatal error messages. The messages in the log file present user with more detailed information about the transformation process. By analyzing these messages, user can know what caused the problem and how to solve it.
The logging method is based on Ant's Logger & Listener interface. By default, this logging method is disabled, and all the messages occur on the screen just like previous releases.
Enhanced Ant command:
To start this new logging method, you need to follow the usage below:
  • At an Ant command prompt, specify the logger by appending -logger org.dita.dost.log.DITAOTBuildLogger in the command parameters, for example:
    ant sample.web -logger org.dita.dost.log.DITAOTBuildLogger
  • At a Java command prompt, the logger is specified internally, so you do not need to specify it again.
Important change and future updates:
DITA-OT 1.2 offers new error handling and logging system. If you invoke your transformation with the Java command line where new error handling and logging system is mandatory, you need to set the CLASSPATH Environment Variable for dost.jar. If you invoke your transformation with an ant script, you need to do one more step after the above setting. That is, add a parameter in your command to invoke an ant script. For example, use:
ant
-f ant\sample_xhtml.xml -logger org.dita.dost.log.DITAOTBuildLogger

instead of:
ant -f ant\sample_xhtml.xml

to start a transformation defined in ant script file ant\sample_xhtml.xml.

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
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 Resources 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
JavadocDITADoclet
C:\\DITA\>Javadoc @options @packages
C:\\DITA\>DITADoclet.exe @options @packages
Options
-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
Options
-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
Packages
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
Packages
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
CHM with draft comments
Figure 27. CHM without draft comments
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
Eclipse on-line help

DITADoclet advantages

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

Search
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.
Index
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

Downloads

DescriptionNameSize
DITADoclet and DemoDITADoclet.zip3004KB
Eclipse Pluginorg.dita.dost.zip626KB

Resources

Learn

  • Explore these developerWorks articles about DITA:
  • Eclipse Platform: Stay current on Eclipse, its news, plugins, and community. Plus explore Eclipse with these articles:
    • Documenting your project using the Eclipse help system (Arthur Barr, developerWorks, January 2004): Build easy-to-use and searchable help documentation.
    • The Mastering Eclipse V3.4 series (Prashant Deva, developerWorks, October-November 2008, January 2009): In this three-part series, go through the ins and outs of the Eclipse IDE workbench, the JDT, and JDT text editor tips and tricks. By the end of the series, you'll be on par with advanced users.
  • DITA Open Toolkit: Learn more about this implementation of the OASIS DITA Technical Committee's specification for DITA DTDs and Schemas. The Toolkit transforms DITA content (maps and topics) into deliverable formats.
  • XML technical library: See the developerWorks XML Zone for a wide range of technical articles and tips, tutorials, standards, and IBM Redbooks.
  • developerWorks technical events and webcasts: Stay current with technology in these sessions.
  • developerWorks podcasts: Listen to interesting interviews and discussions for software developers.

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into XML on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=XML, Java technology, Rational, WebSphere, DevOps
ArticleID=368020
ArticleTitle=Generate DITA Java API reference documentation using DITADoclet and DITA API specialization
publish-date=03172014