Quick Review

In Part 1 of this series, How Java API reference documentation is organized in Eclipse Help , I introduced a different approach for generating easy-to-use and searchable Java application programming interfaces (API) reference documentation.

This article discusses the JavaTOC doclet tool, how to use it and how to extend it. The approach uses the Javadoc standard solution and the Eclipse Plug-in Help System generated using the JavaTOC doclet that I developed. The JavaTOC doclet tool generates the necessary XML table-of-contents (TOC) navigation files for the Eclipse Help system, and the Sun Javadoc API reference documentation in HTML format. To understand the approach, I included a demo example that uses the Sun Javadoc and the JavaTOC doclet tool (using Command Prompt).

Back to top

Eclipse Javadoc API reference structure generated with JavaTOC doclet

Design Constraints

You can run JavaTOC doclet and Javadoc to generate the Java API reference documentation, the table of contents (TOC) navigation and the plug-in structure. Or, you can run just the JavaTOC doclet to generate the TOC navigation from the existing documentation that was produced by developer and delivered to you.

Workflow

For each plug-in that you want to contribute to Eclipse help system (Java API reference section), should in general, proceed with the following workflow:

• Run JavaTOC doclet to create all necessary plug-in files for the Eclipse Help system (plugin.xml, primary.plugin.toc.xml, META-INF/MANIFEST.MF, build.properties, and plugin.properties).
  The plugin.xml file, which extends the org.eclipse.help.toc extension point, needs to specify:
1. One XML TOC file, if you have just a couple of Java packages.
2. Multiple XML TOC files, when you have multiple Java packages.
• Run Javadoc (Sun Microsystems, Inc.) on your Java source code files to create the HTML files for the Java API reference documentation.
  
• Test the Java API reference documentation that was generated.
  

Ant is the Java build system that everyone seems to be using now. If you haven't worked with Ant, check out the Jakarta website, or "Open Source Java: Ant".

My preferred way to run the JavaTOC doclet tool is through the Ant build system, but in this article I will show you how to use JavaTOC doclet from Command Prompt.

Building XML TOC files output with command line

The JavaTOC Doclet Toolkit release 1.0.0 provides a Command Line interface as an alternative for users with little knowledge of Ant to easily use the toolkit.

1. Ensure Javadoc is installed on your path. (...\jdk1.5.0_06\bin\javadoc.exe)
   • NOTE: Typically, Javadoc will have a path like C:\Program Files\Java\jdk1.5.0_06\bin.
2. Download the JavaToc Doclet ZIP file and unzip the zip file into a directory of your choice (for example, C:\doclet\ on Windows). It will create a directory JavaTOC with bin\, demo\ and doc\ subdirectory.
   • The bin directory contains the Java classes you need to run the doc expansion as jar libraries. (DocletTOC.jar)
   • The doc directory contains the JavaTOC User Guide and the org.dita.dost.doc plugin API Documentation (an example) in HTML format.
   • The src resources directory contains the Java source files that you can use for the example.
     (you can download the source files directly from the SOURCEFORGE website: DITA-OT1.3_src.zip )
3. Use the @packages option to place the packages fully qualified type name in a separate file.
4. Run the following command from directory c:\doclet> javadoc @tocdoclet @options @packages (Listing 1 thru Listing 3)

-doclet com.ibm.malup.doclet.config.TOCDoclet
-docletpath C:\doclet\bin\TOCNavDoclet.jar

-sourcepath src
-d com.ibm.doc_plugin_name
-overview src/overview-summary.html
-doctitle 'Navigation label'
-version 'plugin_version' -pluginid plugin_id
-provider 'plugin_provider_name' 
-anchor 'plugin_name'

com.ibm.package1
com.ibm.package2
...
com.ibm.packageN 

source\..\..\package1\fileA.java,source\..\..\package2\fileB.java, , ,
source\..\..\packageN\fileN.java 

5. You can modify this files by opening them with NotePad editor.
   • JavaTOC doclet passes the plug-in name, id, version, and the provider-name values to your Eclipse plug-in project, shown in Listing 2.
     The extension point from the org.eclipse.help.toc plug-in identifies this as a plug-in to the help system.
     The file doclet.toc.xml is referenced as being the table of contents for this plug-in; this file will provide the data for the hierarchical information in the left pane of the Eclipse help window.
   • The packages file contains something like what is shown in Listing 3.
6. Running the command: javadoc @tocdoclet @options @packages @removefiles — remove all the classes that you do not want to be exposed (Listing 4).

Parameter	Description
-d <destination directory>	Specifies the destination directory for the generated documentation. By default, this is the current directory (the one designated by "." pathname).
-doclet <class>	Generate output via alternate doclet. To run the doclet, you will need to specify the doclet class on the Javadoc command line using option: -doclet <class>
-sourcepath <pathlist>	Specify where to find the source files. By default, src is the current directory.
-docletpath <path>	Specify where to find the doclet class files
-doctitle <html-code>	Include the title for the Eclipse plug-in. This is reflected in the manifest.mf file: Plugin.name = Building MDA RXE
-overview <file>	Specify where to find the overview documentation (HTML file).
—version <plug-in_version>	Specify the plug-in version id details.
—provider <plug-in_provider>	Specify the plug-in provider name details.
-anchor	Linking is specified by using the fully qualified reference to a table of contents, such as <toc link_to="../the_other_plugin_id/path/to/toc.xml#anchor_id"/>
-notree	The org.eclipse.help.toc contribution specifies one or more associated XML files that contain the structure of your help and its integration with help contributed by other plug-ins. If you are going to generate documentation for a full-size project, specify to create multiple XML TOC files. NOTE: Missing this flag parameter will create only one XML TOC file

7. The doclet generates the output XML files for the plug-in, and several useful files to c:\doclet\com.ibm.doc_plugin_name, which is now your plug-in directory:
• plugin.xml
• plugin.properties
• .project
• META-INF\MANIFEST.MF
• com.ibm.packageN.toc.xml — TOC XML files for building the navigation tree in the help browser
• buildJavaDoc.xml — ANT file for running JavaDoc tool from the Ant environment.
• buildJavaDoc.bat — BAT file for running JavaDoc tool.
8. Run JavaDoc from Command Prompt (buildJavaDoc.bat) to create HTML file for API Documentation.

Back to top

Using the JavaTOC doclet to create one XML TOC file

Now that we have talked about the doclet, let's get into the real example using the JavaTOC doclet with the DITA-OT 1.3 source files (DITA-OT1.3_src.zip) as our example.

A TOC file defines the key entry points into the HTML content files by defining labeled topics mapped to the individual HTML files, and acts like a table of contents for a set of HTML content. This TOC files are sometimes referred to as navigation files since they describe how to navigate the HTML content. A plug-in can have one or more TOC files.

Running org.dita.dost example

Running the bat file: C:\doclet\JavaTOC>TOCDoclet_dost.bat (Listing 5 thru Listing 8)

javadoc @config @options @packages

-doclet com.ibm.malup.doclet.config.TOCDoclet -docletpath C:\doclet\bin\TOCNavDoclet.jar

-sourcepath demo/src
-d demo/output/org.dita.dost.doc
-overview demo/src/overview-summary.html
-doctitle 'Building DITA output'
-pluginid org.dita.dost.doc
-provider XYZ
-version 1.0.1

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

or from Command Prompt C:\doclet\JavaTOC> directory:

javadoc -doclet com.ibm.malup.doclet.config.TOCDoclet -docletpath C:\doclet\JavaTOC\bin\TOCNavDoclet.jar -sourcepath demo/src -d demo/output/org.dita.dost.doc -doctitle 'Building DITA output' -pluginid org.dita.dost.doc -provider XYZ -version 1.0.1 -overview demo/src/overview-summary.html 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

Destination directory for output files

• The doclet generates the output XML files for the plug-in, and several useful files to C:\doclet\JavaTOC\output\org.dita.dost.doc, which is now your plug-in directory (Listing 9):
• plugin.xml
• plugin.properties
• .project
• META-INF\MANIFEST.MF
• org.dita.dost.doc_toc.xml— TOC XML file for building the navigation tree in the help browser.
• buildJavaDoc.xml — ANT file for running JavaDoc tool from the Ant environment.
• buildJavaDoc.bat — BAT file for running JavaDoc tool.

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.0"?>


<!-- ========================================================== -->
<!-- This plug-in declares an online help                       -->
<!--  contribution for IBM Rational Software Modeler.           -->
<!--  Licensed Materials - Property of IBM                      -->
<!-- (c) Copyright IBM Corp. 2006. All Rights Reserved.         -->
<!-- ========================================================== -->

<plugin
    name = "%Plugin.name"
    id = "org.dita.dost.doc"
    version = "7.0.1.0"
    provider-name = "%Plugin.providerName">

  <extension point="org.eclipse.help.toc">
    <toc file="org.dita.dost.doc_toc.xml" primary="true"/>
  </extension>

</plugin>

The plug-in's name, id, version, and provider-name values are auto-generated from the -d, -doctitle, —version and —provider properties (Listing 10).

# NLS_MESSAGEFORMAT_VAR
# ==============================================================================
# Online Help - Translation Instruction: section to be translated
# =============================================================================
Plugin.name = Building DITA output
Plugin.providerName = IBM

The plug-in manifest files externalize their strings by replacing the string with a key (e.g. %pluginName) and create an entry in the plugin.properties file of the form: pluginName = "Online Help Sample Plugin" (Listing 11)

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Doc Plug-in
Bundle-SymbolicName: -pluginid; singleton:=true 
Bundle-Version: 1.0.0
Bundle-Activator: -pluginid.DocPlugin
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
 org.eclipse.core.runtime
Eclipse-AutoStart: true

The extension point of the org.eclipse.help.toc plug-in identifies this as a plug-in to the help system. The file doclet.toc.xml is referenced as being the table of contents for this plug-in; this file will provide the data for the hierarchical information in the left pane of the Eclipse help window.
A simple file contains something like what is shown in Listing 12.

<?xml version="1.0" encoding="UTF-8"?>

<?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Building DITA output">
   <topic label="Overview" href="overview-summary.html">
  <topic label="org.dita.dost.index Package" href="../index/package-summary.html">
    <topic label="IndexTerm" href="../index/IndexTerm.html"/>
    <topic label="IndexTermCollection" href="../index/IndexTermCollection.html"/>
    <topic label="IndexTermTarget" href="../index/IndexTermTarget.html"/>
    <topic label="TopicrefElement" href="../index/TopicrefElement.html"/>
  </topic>
  <topic label="org.dita.dost.invoker Package" href="../invoker/package-summary.html">
    <topic label="AntInvoker" href="../invoker/AntInvoker.html"/>
    <topic label="CommandLineInvoker" href="../invoker/CommandLineInvoker.html"/>
    <topic label="JavaInvoker" href="../invoker/JavaInvoker.html"/>
  </topic>
  <topic label="org.dita.dost.log Package" href="../log/package-summary.html">
    <topic label="DITAOTBuildLogger" href="../log/DITAOTBuildLogger.html"/>
    <topic label="DITAOTEchoTask" href="../log/DITAOTEchoTask.html"/>
    <topic label="DITAOTFailTask" href="../log/DITAOTFailTask.html"/>
    <topic label="DITAOTFileLogger" href="../log/DITAOTFileLogger.html"/>
    <topic label="DITAOTJavaLogger" href="../log/DITAOTJavaLogger.html"/>
    <topic label="LogConfigTask" href="../log/LogConfigTask.html"/>
    <topic label="MessageBean" href="../log/MessageBean.html"/>
    <topic label="MessageUtils" href="../log/MessageUtils.html"/>
  </topic>
  <topic label="org.dita.dost.module Package" href="../module/package-summary.html">
    <topic label="Content" href="../module/Content.html"/>
    <topic label="AbstractPipelineModule" href="../module/AbstractPipelineModule.html"/>
    <topic label="ContentImpl" href="../module/ContentImpl.html"/>
    <topic label="DebugAndFilterModule" href="../module/DebugAndFilterModule.html"/>
    <topic label="GenMapAndTopicListModule" href="../module/MapAndTopicListModule.html"/>
    <topic label="IndexTermExtractModule" href="../module/IndexTermExtractModule.html"/>
    <topic label="ModuleFactory" href="../module/ModuleFactory.html"/>
    <topic label="MoveIndexModule" href="../module/MoveIndexModule.html"/>
    <topic label="MoveLinksModule" href="../module/MoveLinksModule.html"/>
  </topic>
  <topic label="org.dita.dost.pipeline Package" href="../pipeline/package-summary.html">
    <topic label="AbstractPipelineInput" href="../pipeline/AbstractPipelineInput.html"/>
    <topic label="AbstractPipelineOutput" href="../pipeline/AbstractPipelineOutput.html"/>
    <topic label="AbstractFacade" href="../pipeline/AbstractFacade.html"/>
    <topic label="PipelineFacade" href="../pipeline/PipelineFacade.html"/>
    <topic label="PipelineHashIO" href="../pipeline/PipelineHashIO.html"/>
  </topic>
  <topic label="org.dita.dost.platform Package" href="../platform/package-summary.html">
    <topic label="IAction" href="../platform/IAction.html"/>
    <topic label="DescParser" href="../platform/DescParser.html"/>
    <topic label="Features" href="../platform/Features.html"/>
    <topic label="FileGenerator" href="../platform/FileGenerator.html"/>
    <topic label="ImportAction" href="../platform/ImportAction.html"/>
    <topic label="InsertAction" href="../platform/InsertAction.html"/>
    <topic label="Integrator" href="../platform/Integrator.html"/>
    <topic label="IntegratorTask" href="../platform/IntegratorTask.html"/>
  </topic>
  <topic label="org.dita.dost.reader Package" href="../reader/package-summary.html">
    <topic label="AbstractReader" href="../reader/AbstractReader.html"/>
    <topic label="AbstractXMLReader" href="../reader/AbstractXMLReader.html"/>
    <topic label="DitamapIndexTermReader" href="../reader/DitamapIndexTermReader.html"/>
    <topic label="DitaValReader" href="../reader/DitaValReader.html"/>
    <topic label="GenListModuleReader" href="../reader/GenListModuleReader.html"/>
    <topic label="IndexTermReader" href="../reader/IndexTermReader.html"/>
    <topic label="ListReader" href="../reader/ListReader.html"/>
    <topic label="MapIndexReader" href="../reader/MapIndexReader.html"/>
  </topic>
  <topic label="org.dita.dost.util Package" href="../util/package-summary.html">
    <topic label="CatalogParser" href="../util/CatalogParser.html"/>
    <topic label="CatalogUtils" href="../util/CatalogUtils.html"/>
    <topic label="Constants" href="../util/Constants.html"/>
    <topic label="DITAOTCopy" href="../util/DITAOTCopy.html"/>
    <topic label="FileUtils" href="../util/FileUtils.html"/>
    <topic label="IsAbsolute" href="../util/IsAbsolute.html"/>
    <topic label="StringUtils" href="../util/StringUtils.html"/>
  </topic>
  <topic label="org.dita.dost.writer Package" href="../writer/package-summary.html">
    <topic label="AbstractWriter" href="../writer/AbstractWriter.html"/>
    <topic label="AbstractXMLWriter" href="../writer/AbstractXMLWriter.html"/>
    <topic label="CHMIndexWriter" href="../writer/CHMIndexWriter.html"/>
    <topic label="DitaIndexWriter" href="../writer/DitaIndexWriter.html"/>
    <topic label="DitaLinksWriter" href="../writer/DitaLinksWriter.html"/>
    <topic label="DitaWriter" href="../writer/DitaWriter.html"/>
    <topic label="JavaHelpIndexWriter" href="../writer/JavaHelpIndexWriter.html"/>
    <topic label="PropertiesWriter" href="../writer/PropertiesWriter.html"/>
  </topic>
  </topic>
  </toc>

Now we have all plug-in files, which have been tagged for Eclipse Help system. You have the structure for the Java API reference documentation that enables navigation within an Eclipse help plug-in through a table-of-contents (TOC) written as an XML document. The browsable and searchable needs are met with this structured information approach using XML.

The documentation is provided with a collapsible index on the left side, and HTML documentation on the right

Running JavaDoc to create HTML file

Run JavaDoc from Command Prompt from C:\doclet\JavaTOC\demo\output\org.dita.dost.doc directory (buildJavaDoc.bat) to create the HTML files for the API reference documentation.

C:\doclet\JavaTOC\demo\output\org.dita.dost.doc>javadoc -sourcepath src -d doc -doctitle "Building DITA output" -overview src\overview.html 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

Back to top

Using the JavaTOC doclet to create multiple XML TOC files

A single Java API can typically consist of seven or more package files. With JavaTOC doclet, you only maintain one file (package.txt), and the rest is generated. You dramatically reduce development time, and can concentrate on documenting the API, while JavaTOC generates 100% of the plug-in help code for you.

Running same org.dita.dost example

Run Command Prompt JavaTOC doclet from C:\doclet\ directory. C:\doclet\JavaTOC>javadoc @tocdoclet options.org.dita.dost @packages (Listing 13)

 -sourcepath demo/src
-d demo/output2/org.dita.dost.doc
-overview src/overview-summary.html
-provider XYZ -doctitle 'Building DITA output'
-notree

where I introduce the -notree parameter:

or

C:\doclet\JavaTOC>javadoc -doclet com.ibm.malup.doclet.config.TOCDoclet -docletpath C:\doclet\JavaTOC\bin\TOCNavDoclet.jar -sourcepath demo/src -d demo/output/org.dita.dost.doc -doctitle 'Building DITA output' -pluginid org.dita.dost.doc -provider XYZ -version 1.0.1 -overview demo/src/overview-summary.html -notree 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

Destination directory for output files (org.dita.dost.doc)

• The doclet generates the output XML files for the plug-in, and several useful files to C:\doclet\JavaTOC\demo\output\org.dita.dost.doc. This is your new plug-in directory:
• plugin.xml
• plugin.properties
• META-INF\MANIFEST.MF
• doclet.toc.xml
  org.dita.dost.index.toc.xml,
  org.dita.dost.invoker.toc.xml,
  org.dita.dost.log.toc.xml,
  org.dita.dost.module.toc.xml,
  org.dita.dost.pipeline.toc.xml,
  org.dita.dost.platform.toc.xml,
  org.dita.dost.reader.toc.xml,
  org.dita.dost.util.toc.xml,
  org.dita.dost.writer.toc.xml — TOC XML files for building the navigation tree in the help browser
• buildJavaDoc.xml — ANT file for running JavaDoc tool from the Ant environment.
• buildJavaDoc.bat — BAT file for running JavaDoc tool.

The file org.dita.dost.index.toc.xml is just another table of contents, and should take exactly the same format as any other toc.xml file (Listing 14).

 <?xml version="1.0" encoding="UTF-8"?>
 <?eclipse version="1.0"?>

 <plugin
    name = "%Plugin.name"
    id = "org.dita.dost.user.doc"
    version = "7.0.1.0"
    provider-name = "%Plugin.providerName">

  <extension point="org.eclipse.help.toc">

   <toc file="doclet.toc.xml" primary="true"/>

    <toc file="org.dita.dost.exception.toc.xml"/>
    <toc file="org.dita.dost.index.toc.xml"/>
    <toc file="org.dita.dost.invoker.toc.xml"/>
    <toc file="org.dita.dost.log.toc.xml"/>
    <toc file="org.dita.dost.module.toc.xml"/>
    <toc file="org.dita.dost.pipeline.toc.xml"/>
    <toc file="org.dita.dost.platform.toc.xml"/>
    <toc file="org.dita.dost.reader.toc.xml"/>
    <toc file="org.dita.dost.util.toc.xml"/>
    <toc file="org.dita.dost.writer.toc.xml"/>


  </extension>

</plugin>

where "doclet.toc.xml" is the primary file. The important thing here is to define this table of contents as a primary toc (Listing 15).

 <?xml version="1.0" encoding="UTF-8"?>
 <?NLS TYPE="org.eclipse.help.toc"?>

<toc label="Building DITA output">
   <topic label="Overview" href="doc\overview-summary.html">
        <link toc="org.dita.dost.exception.toc.xml"/>
        <link toc="org.dita.dost.index.toc.xml"/>
        <link toc="org.dita.dost.invoker.toc.xml"/>
        <link toc="org.dita.dost.log.toc.xml"/>
        <link toc="org.dita.dost.module.toc.xml"/>
        <link toc="org.dita.dost.pipeline.toc.xml"/>
        <link toc="org.dita.dost.platform.toc.xml"/>
        <link toc="org.dita.dost.reader.toc.xml"/>
        <link toc="org.dita.dost.util.toc.xml"/>
        <link toc="org.dita.dost.writer.toc.xml"/>
 </topic>
</toc>

When the documentation is viewed, there will be no difference between using this method and simply including the additional topic elements directly (Listing 16).

 <?xml version="1.0" encoding="UTF-8"?>
 <?NLS TYPE="org.eclipse.help.toc"?>

<toc label="org.dita.dost.index Package" link_to="../doclet.toc.xml#java.packages">
  <topic label="org.dita.dost.index Package" href="~/index/package-overview.html">
           <anchor id="org.dita.dost.index.packages"/>
    <topic label="IndexTerm" href="doc/org/dita/dost/index/IndexTerm.html"/>
    topic label="IndexTermCollection" href="~/index/IndexTermCollection.html"/>
    <topic label="IndexTermTarget" href="doc/org/dita/dost/index/IndexTermTarget.html"/>
    <topic label="TopicrefElement" href="doc/org/dita/dost/index/TopicrefElement.html"/>
  </topic>
</toc>

Having edited or added new API documentation to a source code file, you should generate the documentation to ensure and test that the result is what you expected.

Now take your plug-in and drop it into the Platform’s plugins directory, start Eclipse and choose Help -> Help Contents.

Running JavaDoc to create HTML file

To generate the Java API reference documentation (HTML format) for our example (org.dita.dost):

• Run the javadoc utility on the Java code by executing the command, or
• Run buildJavaDoc.bat batch file (Listing 17).

 javadoc -sourcepath src -d doc -doctitle "DITA XML" -overview src\overview.html
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

Back to top

Packaging the plug-in

Each topic element is represented in the final documentation by an entry in the navigation list. These topics can be nested (they can contain more topics), and each one points to an HTML file. Once you've done this, all you need to do is package everything in the structure shown in Figure 1 (notice that the plug-in directory name matches the id and version attributes of the plug-in defined in the plugin.xml).

As a convenience, and to reduce file size, Eclipse allows you to keep all your actual documentation (the HTML files) in a ZIP file called doc.zip, so you could use the directory structure shown in Figure 2.

Back to top

Viewing your documentation

The easiest way to test your plug-in is to simply drop the entire directory (as above) into the plugins directory of an installed Eclipse Platform, and then launch Eclipse and select Help > Help Contents. You will get a help window with your plug-in added (similar to the one in Figure 3).

Back to top

Notices

The information provided in this document are my observations and techniques as a technical writer, and has not been submitted to any formal IBM test and is distributed "AS IS," without warranty of any kind, either express or implied.
The JavaTOC doclet tool is a published invention, author Mariana Alupului. The invention is part of the IBM Intellectual Property and it is published on www.ip.com.
The use of this information or the implementation of any of these techniques described in this document is the reader's responsibility and depends on the reader's ability to evaluate and integrate them into their operating environment.

Back to top

Conclusion

The JavaTOC doclet presented in this paper can be used to produce Java API reference help documentation based on HTML and a small number of additional documentation elements. Using this doclet, it is easy to create Eclipse platform documentation, which can then be used to produce XML and HTML output formats for existing Eclipse help systems. We have shown how to develop Eclipse platform documentation using the JavaTOC doclet. This free open source solution can simplify your documentation development, allowing you to work just with a doclet and have the plug-in and the reference documentation generated for you. Over time, there will be more and more additions.

In the upcoming articles of developerWorks XML zone series, How Java API Documentation is organized in DITA API specialization, I will describe a process for automatically generating searchable Java API documentation (TOC navigation) using the DITAdoclet tool for the Eclipse Plug-in Help System. We will also look more in-depth at the Java API technology, and some of the value-added enhancements from IBM, including Java DITA API specialization, and how it can be utilized.

Back to top

Download

Information about download methods

Resources

Learn

• Lean more about Sun Microsystems Javadoc tool.
  • See the Javadoc home page for more information about Sun Microsystems Javadoc tool.
  • Explore Doclet.com, a repository of Doclet extensions for the Javadoc tool.
  • The Sun tutorial "How to Write Doc Comments for the Javadoc Tool" describes the rules and philosophy of Javadoc.
  • The Javadoc doclet API lets you write custom Javadoc plug-ins to produce different forms of documentation, HTML, XML or DITA from Javadoc comments.
  
  
• Find more XML resources on the developerWorks XML zone. The developerWorks XML zone contains literally hundreds of articles, tutorials, and tips to help a developer make the most of XML-related applications, but for users trying to find their way in a new topic, all of that information can be overwhelming.
  • Documentation Enhancer for Java from IBM alphaWorks is a tool that enhances Javadoc files by enriching them with new information (semantic information, sorting, and navigability) that is gathered by statically analyzing the corresponding Java class files.
  • See the "Documenting your project using the Eclipse help system" , from IBM developerWorks.
  • The Java language takes an integrated approach to API documentation through the Javadoc comment convention.
    Read David Gallardo article, "Java theory and practice: I have to document THAT?" and learn how to create Eclipse plug-ins using the Plug-in Development Environment's code generation wizard.
  
  
• Find more resources on the Eclipse Platform . Eclipse is an open source community whose projects are focused on providing an extensible development platform and application frameworks for building software.
  • See Javadoc generation wizard allows you to generate Javadoc Generation. It is a user interface for the javadoc.exe tool available in the Java JDK.
  
  
• The DITA Open Toolkit is an implementation of the OASIS DITA Technical Committee's specification for Darwin Information Typing Architecture (DITA) DTDs and Schemas. The Toolkit transforms DITA content (maps and topics) into deliverable formats.
  • Find more about the "DITA XML Specialization for Writing Language-conformant Reference Documentation for API libraries".
  • Find more about the "Java API Reference Specialization" which provides a basis for documenting Java class libraries.
  
  

Get products and technologies

• The DITA API Specialization (javaapiref0.8.zip ) can be used or examined as an example of how to extend the generic API Reference specialization
  
  

Discuss

• Find more about the collaboration between the developers and the writers in my "API documentation process series article"
  • "Creating Javadoc API documentation with directly updated source"
  • "Creating Javadoc API documentation with indirectly updated source".
  
  
• Part 1 of this series, "Javadoc API reference documentation"
  • "How Java API reference documentation is organized in Eclipse Help"
  
  

About the author

Mariana Alupului is a senior technical writer (API) for IBM Software Group, 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 develops the Darwin Information Typing Architecture (DITA) XML specialization for writing language-conformant reference documentation for API libraries. Mariana helps to create the API reference style guidelines and is a member of the corporate ID-Support Council and ID Technical Writers Council. She is a member of the Society for Technical Communication and has presented at the "Beyond the Bleeding Edge" session in 2005.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Quick Review
• Eclipse Javadoc API reference structure generated with JavaToc Doclet
• Using the JavaTOC doclet to create one XML TOC file.
• Using the JavaTOC doclet to create multiple XML TOC files.
• Packaging the plug-in
• Viewing your documentation
• Notices
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

Spring, JRuby, and Ajax development is easier with WebSphere Application Server - a smart Java 5 and J2EE Web services-based application server.

---

• Try: The no-charge WebSphere Application Server Community Edition is a pre-integrated, lightweight Java 5 application server built on Apache Tomcat and other best-of-breed open source software such as OpenEJB, Apache Axis, and Apache Derby.
• Article: The article leverage the Spring Framework and the WebSphere Application Server to improve your J2EE project productivity.
• Tutorial: See how the free WebSphere Application Server and XML can improve the efficiency of your JRuby on Rails and Ajax development.
• Buy: WebSphere Application Server - Express

My developerWorks community

Dig deeper into Rational on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers