Generate DITA Java API reference documentation using ...public.dhe.ibm.com/software/dw/xml/x-DITAdoclet/x-DITAdoclet-pdf.… · Learn to run DITADoclet to generate the DITA Java API

Generate DITA Java API reference documentationusing DITADoclet and DITA API specializationAutomatically create reference documentation from Java sourcewith DITA API specialization

Skill Level: Intermediate

Mariana Alupului ([email protected])Information DeveloperIBM

03 Feb 2009

Updated 11 Dec 2009

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

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

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 easydistribution in many formats. DITADoclet generates the DITA Java API files,automatically creates the DITAMAP and MAPLIST files (DITA Java APIspecialization) for the Java API reference documentation, extracts the developercomments from the Java source code, and migrates the information to the generatedDITA API files.

Generate DITA Java API reference documentation using DITADoclet and DITA API specialization© Copyright IBM Corporation 2009. All rights reserved. Page 1 of 38

mailto:[email protected]

http://www.ibm.com/legal/copytrade.shtml

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 APIreference documentation from Java source code. The Javadoc tool generates thebasic structure for the Java API reference documentation, but the documentation isoften incomplete and limited to developer comments. Changes to developmentteams appear to encourage removal of the API writers and editors from the Java APIreference documentation process altogether. Developers have time to manage onlyJava source code files with incomplete comments. This situation clearly presentsAPI writers and others who are interested in producing high quality APIdocumentation with some substantial challenges.

The DITADoclet and DITA Java API solution provides API writers with the tools togenerate fully documented Java APIs. A fully documented API can serve severalpurposes, but the most important reason is to allow the API users to fullyunderstand, search, and browse the API functions that are available to them. Tocompletely use the functionality of the API, software users require an accurate andfully documented API.

To understand how DITADoclet works, the article also presents some of theimportant notions the Javadoc standard doclet solution uses. For the DITADocletautomatic extraction to work effectively, the Java source code must be documentedaccording to Javadoc strict guidelines. Otherwise, when you extract the commentswith the DITADoclet, it might not process them properly or the resulting APIdocumentation might be incomplete.

developerWorks® ibm.com/developerWorks

Generate DITA Java API reference documentation using DITADoclet and DITA API specializationPage 2 of 38 © Copyright IBM Corporation 2009. All rights reserved.


This article presents the following:

• Prerequisites

• What is DITA Java API specialization?

• DITADoclet installation

• Creating Javadoc documentation using the Eclipse Javadoc Generationwizard (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 XMLeditors that support DITA, see the http://dita.xml.org Web site. I highly recommendthat you use an XML editor to avoid errors in tagging. Many different XML editors areavailable: Arbortext Editor™, <oXygen/>® XML Editor, XMLBuddy™ (an Eclipseplugin), Altova® XMLSpy®, OpenOffice.org, and more. I recommend using theArbortext 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 APIwriter, want to know more about how you can provide improved Java API referencesdocumentation.

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

Prerequisites

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

ibm.com/developerWorks developerWorks®


http://dita.xml.org/


• 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 plugginginto 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 JavaIDE

• Eclipse is the base IDE, but there are many Java-related plugins forEclipse, and several commercial IDEs built on top of Eclipse:

• Rational® Software Architect is a comprehensive integrateddevelopment environment for visually designing, constructing, testing,profiling and deploying applications

• Rational Application Developer for WebSphere Software extendsEclipse with visual development features

• IBM® WebSphere® Studio is a powerful and popular J2EE IDE fromIBM

• IBM WebSphere Studio Site Developer for Java is a Java IDE forWindows and Linux

• Sun Java Studio Creator

• JBuilder

To download these plug-ins, see Resources. I recommend running DITADocleteither 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 DITADocletinstallation below.

DITA enforces consistent, complete, and correct technical documentation. DITA APIspecialization represents a package of DITA topic types to produce Java APIdocumentation files. DITADoclet generates the DITA files directly from the Javasource 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 topicspecialization

• April, 2004: OASIS Technical Committee for DITA formed

• February, 2005: SourceForge begins DITA Open Toolkitsupport

• June, 2005: DITA v1.0 is approved as an OASISstandard

• 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 anytext editor, XML editors allow you to insert and modify tags easily while conformingto the DITA DTD and schemas. I do recommend that you use an XML editor to voiderrors in tagging. Available XML editors include Arbortext Editor, oXygen, XMLBuddy (an Eclipse plugin), Altova XML Spy, and others.

To learn more about DITA, how to create or edit DITA files, and find more XMLeditors 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 underthe terms of the GNU General Public License as published by the Free SoftwareFoundation. 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 DITAarchitecture through the DTD elements for generic (all programming languages) andJava programming language. The DITA API specialization includes topic types andelements for documenting generic and Java API references. Each language-specificDITA API specialization consists of modules. A module is a topic type designed for aspecific task such as describing an API package or class. Each module includes theappropriate 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 APIreference 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 programminglanguages.

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 thesystem 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 apath similar to C:\Program Files\Java\jdk1.5.0_06\. To determine whichJava version you have installed on your system, type at the commandprompt: Java -version

• If your Java version is not recent, download the JDK, J2RE, or JRE fromthe Sun download site (see Resources for the link.)

Install Eclipse Classic

• Download Eclipse Classic for Windows, or IBM Rational Developer, orRational Software Architect Standard Edition, and unzip the zip file into adirectory of your choice (for example, C:\eclipse\ on Windows). SeeResources for the links.

• The most important thing is to be sure that the Eclipse installation pathwill not contain any spaces on the Windows platform. For more details onthe different tools installations, please refer to the official Eclipsedocumentation. To check whether you have the Javadoc tool installed,open a command prompt and type Javadoc. If you receive an error, youdo not have Javadoc (jdk1.5.0_xx), and you need to downloadjdk1.5.0_xx, from the Sun site, and add the directory to your Windowspath: C:\Program Files\Java\jdk1.5.0_xx.

Install DITADoclet

• Download the DITADoclet Tool zip file and unzip it into a directory of yourchoice (for example, C:\DITA\ on Windows). It will create a directory\DITA containing DITADoclet.exe, ReadeMe.txt, and a \demosubdirectory.

• The \demo subdirectory contains the \src resources directory, theoptions, and packages.




• The \src resources directory contains the Java source files which youwill 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. Typicallythis is located inside the directory called \workspace, where you installedEclipse in a subdirectory. If you are using a shortcut or script to launchEclipse, then it will be under the current working directory of that shortcutor 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 theEclipse workspace directory. This will create a Java project namedorg.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. Tocomplete and test your DITA API files, you need to transform .dita files to .xhtmlfiles. You can use DITA Open Toolkit to transform the DITA Java API files orgenerate output from DITA API files. You need to install both apiref and javaapirefplugins 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.8and 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 brieflyreview the Javadoc tool. A detailed description of the Javadoc tool options isprovided with the JDK documentation. If you are familiar with the Javadoc tool, youcan use DITADoclet right away. The Javadoc tool (or DITADoclet) parses the sourcefiles, extracts the Javadoc comments, and builds an internal collection of thedocumentation 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 theprocess.

2. In Eclipse, on the left pane in the Package Explorer view, select the Javasource code for which Javadoc needs to be generated (for this example,you use one of the Eclipse plug-ins, org.dita.dost.) Right-click onorg.dita.dost, and select Export from the drop-down list. The Exportwindow 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:\ProgramFiles\Java\jdk1.5.0_06\bin\Javadoc.exe (see Figure 1).Figure 1. Select javadoc.exe path

5. In the Generate Javadoc window, select the packages that you want toexport to the Javadoc files. This list is initialized by the Eclipse workbenchselection. You can select only one project as you can use only one projectclasspath at a time when running the Javadoc tool.

6. To filter the members of the package, select the visibility (you willnormally select Public.)

• The choices are: -package, -private, -protected, or -public as inFigure 2.Figure 2. Select the member visibility

• Table 1 illustrates which members to select according to the visibilityyou want. -public chooses the fewest, and -private chooses thegreatest number of members.

Table 1. Member visibility

Option Documents these classes

-public public . . .

-protected public protected . .




-package public protected (package) .

-private public protected (package) private

1. Select Use Standard Doclet to start the Javadoc command with thestandard doclet (default).

• Destination: Select the destination to which the standard doclet willwrite the generated documentation. The destination is a standarddoclet-specific argument, and therefore not enabled when using acustom doclet. The destination to which the standard doclet will writecan be, for example, the workspace subdirectory\workspace\doc.dita.dost\output.

3. Click Next to specify additional Javadoc generation options.

4. Deselect Overview as in Figure 3. If selected, this option specifies thatJavadoc should retrieve the text for the overview documentation from thesource file specified and place it on the Overview page (index.html).Figure 3. Overview page location

5. Click Next to specify additional Javadoc generation options.

6. Specify the title to be placed near the top of the index.html file. If you donot select and specify the document title, the Javadoc tool will not add itto the Overview page.Figure 4. Specify the document title

Additional Javadoc options

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

1. To speed the JavaDoc process and turn off any informational messagesfrom the Javadoc, I suggest using the -quiet option to help create theJavadoc comments. (Hint: -verbose is another option that you can use.The -verbose option causes the compiler and Javadoc to print outmessages about which source files are being compiled and what classfiles are being documented.)




Figure 5. Specify VM options and Javadoc options

2. The doclet generates the output HTML files for the plug-in documentationin the workspace subdirectory \workspace\org.dita.dost\output\, which isyour plug-in documentation directory.

3. Click Finish to generate the Javadoc documentation. You watch theprogress of the JavaDoc generation using the console view.

Javadoc obtains all its information and text from the Java source files with twoexceptions: an overview text file and a text file for each package. Both exceptionsare optional. The files created by Javadoc are index.html andpackage-summary.html respectively. When you use the standard Javadoc, thegenerated overview and package files are HTML files without any information. Thepackage documentation provides developers with the necessary information aboutusing the packages. The package information is useful in understanding how thingswork together and might include code, prototype, structure chart diagrams, designpatterns, coding standards, and so on. If you select the option of opening the indexfile in a browser, then after generation of Javadoc, you will find the Javadoc pageindex.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 referencedocumentation. In the next section, you'll see how to create Java API referencedocumentation 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 buildsDITA files directly from Java API source code files. The goal of this design is tomake it easy for API technical writers to leverage their existing Eclipse JavadocGeneration wizard knowledge and to only have to learn a very small set of DITAdocumentation-specific differences:

• DITADoclet generates the documentation with the same overall structureas the documentation generated by the Standard Doclet.




• DITADoclet supports all options provided by the Standard Doclet, butconsiders 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, whileDITADoclet does not.

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

1. In Eclipse, on the left pane, select org.dita.dost, the source code plug-infor which you will generate Javadoc.

2. Right-click on the selected plug-in, and, from the drop down list selectExport. The Export window opens.

3. Select Javadoc and click Next. The Generate Javadoc window opens.Figure 6. Javadoc generation wizard (Standard Doclet) with GenerateJavadoc window open




4. In the Javadoc command field, specify the path to DITADoclet.exe.When you installed DITADoclet, it was probably installed atC:\DITA\DITADoclet.exe.

5. In the Generate Javadoc window select the packages that you want toexport 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 classpathat 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 Javapublic elements, select members with visibility Public.

7. Select Use Standard Doclet to start the Javadoc command with thestandard doclet (default).

8. Specify the destination to which the standard doclet will write thegenerated documentation. (The destination is a standard doclet-specificargument, and therefore not enabled when using a custom doclet.) Thedestination to which the standard doclet will write can be, for example, theworkspace subdirectory, specified as ..\workspace\doc.dita.dost\topics.

9. Click Next for the Basic Options.Figure 7. Javadoc generation wizard (Standard Doclet) - select basicJavadoc options




10. In the Document title field, specify the title to place near the top of theoverview summary file. If you omit the document title, DITADoclet will adda 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 createthe hierarchy tree page with or without input for this flag option.

• Generate navigation bar: The DITADoclet will automatically createthe navigation bar for every page with or without input for this flagoption.

• Generate index: The DITADoclet will automatically create the indexpage with or without input for this flag option.

• Separate index per letter: The DITADoclet will not create separateindex per letter pages.

13. For the Document these tags options, deselect the check boxes as inFigure 7.




• @author: The DITADoclet will automatically add the author to themeta 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 deprecatedinformation to the .dita page with or without input for this flag option.

• @deprecated list: The DITADoclet will not create a deprecated listpage.

15. Keep in mind that the DITADoclet tool takes into consideration only theDestination field value and the Document title options. In this example,the value for Destination is ..\workspace\doc.dita.dost\topics. The valuefor the Document title is DITA-OT. Without a specified value for theDestination field, the DITADoclet tool will create all .dita files in yoursource code folder (\src). If you do not specify the Document title fieldvalue, the DITADoclet Tool will add a default title Building DITA output.

16. At this point you have not created an overview.html file, so do not selectthe Overview check box. (When you run the tool for the second time, youcan select the newly generated overview.html file from your\workspace\src folder.)Figure 8. Do not specify the overview page path

17. Click Next for the Extra Javadoc options (path names with white spacesmust be enclosed in quotes). These options are elective.Figure 9. 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

19. The options -contributor and -provider add a prolog section to all DITAgenerated files that contains the name of the writer, the name of thecontributor, the provider name, the date of generation, and so on. See theexample below.

• The creator author <author type="creator">Lian,




Li</author> comes from source code @author javadoc tags.

• The contributor author <author type="contributor">MarianaAlupului</author> comes from the -contributor Javadoc optionas 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>

20. Click Finish to generate the DITA API documentation.

Additional warnings

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

Figure 10. 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 -debugoption scenarios, so you can see what happens within the generation of thedocumentation in the Eclipse system. You can also send the log files to developersto help them understand which source files have missing information, warnings, andso 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 theDITADoclet 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 elementsnecessary to describe the package, or set of packages, and its components.

Figure 11. 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 attributeson the elements in your DITA source. With these properties, you can turn text on oroff; that is, hide text or show text based on the properties that you declared. If you donot use the attribute values in your file, you can remove the attribute entirely fromyour ditaval file. If you use the values in your files, but do not want to flag it rightnow, 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

org.dita.dost.doc.maplist

The maplist allows you to include a ditamap and a reltable.ditamap file. The map listacts 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




Hierarchy files

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

• 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

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

allnames.dita

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

Figure 16. Index in the allnames.dita file




allclasses.dita

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

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

You do not need to edit the tree.dita, allnames.dita, or allclasses.dita files. Edit themonly 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 EpicEditor. The file provides the writer with a visual representation of information that ismissing from the Java source code and where the writer can enter the missinginformation 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 greenhighlighted text generated by the DITADoclet (fos file) directly from the Java sourcecode. It highlights, in green, the missing comments and provides a possible




documentation alternative. Figure 18 shows a DITA file generated with DITADocletand opened in Epic Editor.

Figure 18. 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. Italso creates the overview-summary.dita file (Figure 19), and saves it in thesubdirectory /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




When you run DITADoclet for the second time, you have already generated theOverview (overview.html). Now you can specify that DITADoclet should retrieve thetext 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

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

When you first run the DITADoclet tool, the tool will create the package.html andpackage-summary.dita file. The tool generates the package.html file if the file is notpresent in Java source code. See Figure 21 for an example of the generatedtemplate for the package-summary.dita file. (To prevent the DITADoclet from




overriding the package-summary.dita information, right-click on thepackage-summary.dita file. Select Properties and, for the Attributes, selectRead-only. This will lock the file content.)

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

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

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




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

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

Figure 23. Document as seen in a browser[Short description]

The main package org.dita.dost.log contains the class DITAOTBuildLogger which isresponsible 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, andfatal error messages. The messages in the log file present user with more detailedinformation about the transformation process. By analyzing these messages, user can knowwhat caused the problem and how to solve it.The logging method is based on Ant's Logger & Listener interface. By default, this loggingmethod 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 -loggerorg.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 tospecify it again.

Important change and future updates:DITA-OT 1.2 offers new error handling and logging system. If you invoke your transformationwith the Java command line where new error handling and logging system is mandatory, youneed to set the CLASSPATH Environment Variable for dost.jar. If you invoke yourtransformation with an ant script, you need to do one more step after the above setting. Thatis, 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 -dcommand option, and into subdirectories of the root output directory. DITADocletautomatically creates the root output directory and all of the subdirectories. Figure24 shows the directory structure and the names of the default files created by theDITADoclet using an example of the directory structure generated for your samplepackage, org.dita.dost. The left side shows the Java source code and its componentfiles. In the right side, you can see the DITA files generated from this Java sourcecode 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 verificationprocess of the documentation after changes to Javadoc comments are made in Javasource code.




Creating Java API reference documentation using DITADocletand command prompt line

It is important to know what parameters Javadoc reads and uses, and theparameters that DITADoclet reads and uses. If you run Javadoc -help, you will seethat the Javadoc tool has two sets of command-line options. One set is generic andwill 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. Yourcustom doclets can also define their own command prompt line options. Thisdocumentation contains only detailed descriptions of all options provided forDITADoclet. A detailed description of the Javadoc tool options is provided with theJDK documentation.

DITADoclet release 1.1.3 (see Resources for a link) provides a command lineinterface as an alternative so users with little knowledge of Eclipse can easily usethe toolkit.

Running Javadoc for the org.dita.dost example

1. See if Javadoc is installed on your path. Typically, Javadoc will have apath 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 ina separate file.

4. Run the following command from your DITA directory C:\DITA\>: Javadoc@options @packages

Figure 25. Options and packages using the exampleJavadoc DITADoclet

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

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




-navbar-index-noauthor-version-deprecated-public

Packages

org.dita.dost.indexorg.dita.dost.invokerorg.dita.dost.logorg.dita.dost.moduleorg.dita.dost.pipelineorg.dita.dost.platformorg.dita.dost.readerorg.dita.dost.utilorg.dita.dost.writerorg.dita.dost.exception

Packages

org.dita.dost.indexorg.dita.dost.invokerorg.dita.dost.logorg.dita.dost.moduleorg.dita.dost.pipelineorg.dita.dost.platformorg.dita.dost.readerorg.dita.dost.utilorg.dita.dost.writerorg.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 toplace 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 followingcommand from your directory C:\DITA\: DITADoclet @options@packages

2. If you choose to type the entire command in the command line, it will looksomething like this:DITADoclet.exe -sourcepath demo/src -ddemo/output/org.dita.dost.doc -overviewdemo/src/overview-summary.html -doctitle 'Building DITA output'-provider IBM -contributor "Mariana Alupului" org.dita.dost.indexorg.dita.dost.invoker org.dita.dost.log org.dita.dost.moduleorg.dita.dost.pipeline org.dita.dost.platform org.dita.dost.readerorg.dita.dost.util org.dita.dost.writer org.dita.dost.exceptionorg.dita.dost.pipeline org.dita.dost.platform org.dita.dost.readerorg.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 withthe WordPad editor.

• Run the command: DITADoclet.exe @options @packages.

Running DITA-OT transformer to generate XHTML files fromDITA

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

DITA-OT transformer has the capability to generate HTMLHelp (CHM). See Figures26 and 27 for screen captures of DITA-OT transformer examples of CHM files, thefirst 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 andfully documented set of Java API reference documentation will not contain any draftcomments highlighted in green (see Figure 27).

API writers can use the DITADoclet testing solution to identify the missinginformation from the Java source code, and also test their work for complete andfully documented reference files before they deliver the source code to the onlineHelp.

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




Figure 28. Eclipse on-line help

DITADoclet advantages

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

SearchProvides an efficient way to retrieve methods and classes/or interfaces. TheJavadoc system does not provide such a search mechanism for the table ofcontents (TOC).

NavigationProvides a TOC navigation that is generated automatically directly from theJava source code.

IndexThe 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 theminto context (for example, gives the containing class for a method or field) andlinks to the document describing the entry.

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

DITADoclet disadvantages

You can use the tool to create DITA Java API files only from Java source filesversion 1.4. The next version of DITA API specialization and DITADoclet will supportJava 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 thatcontributed 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; UserAssistance: 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 DAnderson

• 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

Description Name Size Downloadmethod

DITADoclet and Demo DITADoclet.zip 3004KB HTTP

Eclipse Plugin org.dita.dost.zip 626KB HTTP

Information about download methods



http://public.dhe.ibm.com/software/dw/xml/x-DITAdoclet/DITADoclet.zip

http://public.dhe.ibm.com/software/dw/xml/x-DITAdoclet/org.dita.dost.zip

http://www.ibm.com/developerworks/library/whichmethod.html


Resources

Learn

• Explore these developerWorks articles about DITA:

• Migrating HTML to DITA, Part 1: Simple steps to move from HTML to DITA(Robert Anderson, Don Day, Erik Hennum; developerWorks, January2005): Get a quick start with DITA using HTML topics that are alreadyavailable. You'll migrate info with a XSLT transform and learn how toensure quality results.

• Migrating HTML to DITA, Part 2: Extend the migration for more robustresults (Robert Anderson, developerWorks, February 2005): Find moredetails about migration, and how to override it for ideal results.

• Introduction to DITA (Don Day, Michael Priestley, David Schell; October2003): Read about this road map for DITA: what it is and how to apply it totechnical documentation..

• Specializing topic types in DITA (Michael Priestley, October 2003): Createnew topic-based document types for easy assembly into various deliverycontexts.

• The DITA FAQ (Don Day, Michael Priestley, Gretchen Hargis; November2004): Review the tips and techniques, and answers for general DITAquestions.

• Specializing domains in DITA (Erik Hennum, updated September 2005):Find great flexibility in extending and reusing information types to extendyour base DTD.

• 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 helpdocumentation.

• The Mastering Eclipse V3.4 series (Prashant Deva, developerWorks,October-November 2008, January 2009): In this three-part series, gothrough the ins and outs of the Eclipse IDE workbench, the JDT, and JDTtext editor tips and tricks. By the end of the series, you'll be on par withadvanced users.

• DITA Open Toolkit: Learn more about this implementation of the OASIS DITATechnical Committee's specification for DITA DTDs and Schemas. The Toolkittransforms DITA content (maps and topics) into deliverable formats.



http://www.ibm.com/developerworks/xml/library/x-dita8a/

http://www.ibm.com/developerworks/xml/library/x-dita8b/

http://www.ibm.com/developerworks/xml/library/x-dita8b/

http://www.ibm.com/developerworks/xml/library/x-dita1/

http://www.ibm.com/developerworks/xml/library/x-dita2/index.html

http://www.ibm.com/developerworks/xml/library/x-dita3/index.html

http://www.ibm.com/developerworks/xml/library/x-dita5/

http://www.eclipse.org/

http://www.ibm.com/developerworks/opensource/library/os-echelp/

http://www.ibm.com/developerworks/views/opensource/libraryview.jsp?search_by=mastering+eclipse+v3.4,&S_TACT=105AGX06&S_CMP=art

http://sourceforge.net/project/showfiles.php?group_id=132728


• Java API Reference Specialization: Find the plugin that provides a basisfor documenting Java class libraries.

• IBM XML certification: Find out how you can become an IBM-CertifiedDeveloper in XML and related technologies.

• XML technical library: See the developerWorks XML Zone for a wide range oftechnical articles and tips, tutorials, standards, and IBM Redbooks.

• developerWorks technical events and webcasts: Stay current with technology inthese sessions.

• developerWorks podcasts: Listen to interesting interviews and discussions forsoftware developers.

Get products and technologies

• Rational Software Architect: Try this comprehensive integrated developmentenvironment for visually designing, constructing, testing, profiling, and deployingapplications.

• Rational Application Developer for WebSphere Software: Extend Eclipse withvisual development features.

• IBM WebSphere Studio: Explore a powerful and popular J2EE IDE from IBM.

• IBM WebSphere Studio Site Developer for Java is a Java IDE for Windows andLinux.

• DITA organization site: Learn more about DITA, how to create or edit DITA files,and find more XML editors that support DITA.

• Java EE 5 JDK: Download to streamline application development and maximizeproductivity with a simpler programming model.

• Eclipse Classic for Windows: Download an essential tool for your development.

• IBM Rational Developer: Download and try a complete developmentenvironment for traditional IBM i application development.

• DITA Toolkit source files (DITA-OT1.4_src.zip): Download the DITA Toolkitsource files directly from the SourceForge Web site.

• DITA Open Toolkit: Download this toolkit and transform DITA content (mapsand topics) into deliverable formats.

• GNU General Public License: Redistribute and modify the free DITA OpenPlatform software under these terms as published by the Free SoftwareFoundation.

• DITA Java API Specialization apiref-0.8 Download and use this plugin.



http://dita-ot.sourceforge.net/SourceForgeFiles/doc/download.html

http://www.ibm.com/certify/certs/01001503.shtml

http://www.ibm.com/developerworks/views/xml/library.jsp

http://www.ibm.com/developerworks/offers/techbriefings/?S_TACT=105AGX06&S_CMP=art

http://www.ibm.com/developerworks/podcast/?S_TACT=105AGX06&S_CMP=ART

http://www.ibm.com/developerworks/downloads/r/rsd/

http://www.ibm.com/software/awdtools/developer/application/index.html

http://www.ibm.com/software/awdtools/studiositedev/

http://www.ibm.com/software/awdtools/studiositedev/

http://dita.xml.org/

http://java.sun.com/javaee/downloads/index.jsp

http://www.eclipse.org/downloads/

http://www.ibm.com/developerworks/downloads/r/rdi/

http://sourceforge.net/project/showfiles.php?group_id=132728&package_id=145774&release_id=451323

http://sourceforge.net/project/showfiles.php?group_id=132728

http://www.gnu.org/licenses/



• DITA Java API Specialization Javaapiref-0.8: Download and use this plugin.

• IBM trial software for product evaluation: Build your next project with trialsoftware available for download directly from developerWorks, includingapplication development tools and middleware products from DB2®, Lotus®,Rational®, Tivoli®, and WebSphere®.

Discuss

• XML zone discussion forums: Participate in any of several XML-relateddiscussions.

• developerWorks blogs: Check out these blogs and get involved in thedeveloperWorks community.

About the author

Mariana AlupuluiMariana Alupului is an Information Developer for IBM Rational Software. In additionto documenting and leading API documentation projects for Java, VB, C++, insoftware programming environment, she is a member of the IBM Corporation teamthat developed the Darwin Information Typing Architecture (DITA) XML specializationfor writing language-conformant reference documentation for API libraries. Marianadeveloped DITADoclet to complete Java DITA API specialization. Mariana is the leadof the corporate Java API guidelines workgroup and a member of the corporate IDTechnical Writers Council. She has presented Java DITA API solution at the Societyfor Technical Communication (STC) "Beyond the Bleeding Edge" session (2005) andDITA/TechComm Conference (2008).You can reach Mariana at [email protected]

Trademarks

IBM, the IBM logo, ibm.com, DB2, developerWorks, Lotus, Rational, Tivoli, andWebSphere are trademarks or registered trademarks of International BusinessMachines Corporation in the United States, other countries, or both. These and otherIBM trademarked terms are marked on their first occurrence in this information withthe appropriate symbol (® or ™), indicating US registered or common lawtrademarks owned by IBM at the time this information was published. Suchtrademarks may also be registered or common law trademarks in other countries.See the current list of IBM trademarks.Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered




http://www.ibm.com/developerworks/downloads/?S_TACT=105AGX06&S_CMP=art

http://www.ibm.com/developerworks/forums/dw_xforums.jsp

http://www.ibm.com/developerworks/blogs/

http://www.ibm.com/developerworks/community

mailto:[email protected]



trademarks or trademarks of Adobe Systems Incorporated in the United States,and/or other countries.Altova and XMLSpy are registered trademarks of AltovaArbortext Editor is a trademark of ArbortextJava and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in theUnited States, other countries, or both.Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporationin the United States, other countries, or both.Linux is a trademark of Linus Torvalds in the United States, other countries, or both.<oXygen/> is a registered trademark of SyncRO Soft LtdXMLBuddy is a trademark of Bocaloco Software LLCOther company, product, or service names may be trademarks or service marks ofothers.


