Skip to main content

skip to main content

developerWorks  >  Rational | Open source  >

Java API reference documentation

Part 2: Eclipse Javadoc API reference structure generated using the JavaTOC doclet

developerWorks
Document options

Document options requiring JavaScript are not displayed

Sample code


Rate this page

Help us improve this content


Level: Intermediate

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

26 Dec 2007

This article, Part 2 of a series, describes different approaches for generating easy-to-use and searchable Java application programming interfaces (API) reference documentation.

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

To become a highly skilled Technical Writer (Java API Information Developer), you must acquire a fluent understanding of the Java language, Java API reference documentation generation tools and techniques.

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

Computer programming languages support source code documentation, by providing special symbols that signal the beginning and end of source code descriptions. The symbols and descriptions are collectively known as comments. Java programming language supports three styles of comments: multiline, single-line, and doc.

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)


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


Listing2. options
                -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'


Listing 3. packages
                com.ibm.package1
com.ibm.package2
...
com.ibm.packageN 


Listing 4. removefiles
                source\..\..\package1\fileA.java,source\..\..\package2\fileB.java, , ,
source\..\..\packageN\fileN.java 

  1. 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.
  2. Running the command: javadoc @tocdoclet @options @packages @removefiles — remove all the classes that you do not want to be exposed (Listing 4).


Table of supported parameters provided by JavaTOC doclet:

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> eclipse titleInclude 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).
eclipse title
—version <plug-in_version>Specify the plug-in version id details.
eclipse title
—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"/> eclipse title
-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

  1. 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.
  2. 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)


Listing5. TOCDoclet_dost.bat
                javadoc @config @options @packages


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


Listing 7. options
                -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


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

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.


Listing9. plug-in.xml
                <?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).


Listing10. plugin.properties
                # 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)


Listing11. META-INF\MANIFEST.MF
                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.


Listing12. org.dita.dost.doc_toc.xml
                <?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)


Listing13. options.org.dita.dost
                 -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:

Parameter Description
-notreeSpecify to create multiple XML TOC files
NOTE: Missing this parameter will create only one XML TOC file.

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


Listing14. plug-in.xml
                 <?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).


Listing15. doclet.toc.xml
                 <?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).


Listing16. org.dita.dost.index.toc.xml
                 <?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).


Listing 17. buildJavaDoc.bat
                 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).


Figure 1. Plug-in directory
Plug-in directory

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.


Figure 2. Directory structure of doc.zip
Directory structure of doc.zip


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


Figure 3. Help — Eclipse SDK
 Eclipse SDK Help


Back to top


Notices

"Simplicity is the soul of efficiency". — Austin Freeman

Good writing comment habits are very important to the quality of the code produced as well as to the quality of the final product which uses the code.

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 Java API reference source is owned by programmers, and edited by both programmers and technical writers.

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

DescriptionNameSizeDownload method
Java Toc fileJavaTOC.zip108KBHTTP
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.
  • 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.

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


About the author

Mariana Alupului

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.




Rate this page


Please take a moment to complete this form to help us better serve you.



 


 


Not
useful
Extremely
useful
 


Share this....

digg Digg this story del.icio.us del.icio.us Slashdot Slashdot it!



Back to top