Java API reference documentation

How Java API reference documentation is organized in Eclipse Help

This article describes different approaches for generating easy-to-use and searchable Java application programming interfaces (API) reference documentation.

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

Mariana AlupuluiMariana 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.


developerWorks Contributing author
        level

20 March 2007

Also available in Chinese Japanese Vietnamese

Background

Improving the consumabilty of the product documentation is a key to success for many projects. The success is directly attributable to your efforts to generate and write good documentation.

This material assumes that you are familiar with Java software, Java API references documentation structure, Javadoc generation and want to know more about how to provide improved Java API references documentation.
For beginners, you should acquaint yourself with these:


Build easy-to-use and searchable Java API reference documentation

This article describes different approaches for generating easy-to-use and searchable Java application programming interfaces (API) references documentation. The approaches described are the Javadoc standard solution and the Eclipse Plug-in Help System generated using the JavaTOC doclet that I developed. The JavaTOC doclet creates a table-of-contents (TOC) for the Javadoc API reference documentation helping the user to easily search the API reference documentation for a specific class, interface or method.

The Javadoc API reference documentation needs to be both browsable and searchable. The standard Javadoc does not fully offer this capability. A fully documented API can serve several purposes, but the most important reason is to allow users to fully understand and search the API functions that are available to them. If not properly documented or searchable, even the original author might not understand the source code. The solution is to get into the habit of documenting source code and create searchable structure (TOC navigation) for the Java API references. The JavaTOC doclet resolves this issue by creating searchable structure for the references.

Searching and browsing assumes that the information is sorted by relevance for a particular query, creating any number of ad hoc sequences as a result. For example, in standard Javadoc a search of the API information for a description of a specific method returns the description of the entire class.


Considered Approaches

The solution is to get into the habit of documenting source code. If not properly documented, even the original author might not understand the source code.

There are quite a few tools for generating Java API reference documentation. My current recommendation is JavaTOC doclet used in combination with Javadoc or DITA API specialization.

  • Javadoc is a tool owned by Sun that extracts the developer comments from Java source code and outputs them to HTML. The Javadoc tool generates the basic structure of the Java API reference documentation. The result is Javadoc HTML API documentation for a set of packages and classes.
  • The JavaTOC doclet generates the TOC navigation and the search capability for the Java API references documentation. The IBM DITA API specialization team has developed a package of DITA topic types to produce Java API documentation files and the navigation manifests for references that will be included in the Eclipse Help system.

The following examples (Example of API reference without toc navigation and Example of API reference with toc navigation) use the Java source code from the DITA Open Toolkit. The DITA Open Toolkit release 1.0.2 or above provides a Command Prompt interface as an alternative for users with little knowledge of Ant to use the toolkit easily. After you download the zip file, you can find the source code used for this articles examples in the DITA-OT1.2_src\DITA-OT1.2-src\src directory.


About Javadoc and the JavaTOC doclet

The biggest difference between the standard Javadoc Help and the customized Eclipse Javadoc Help is the TOC navigation provided. The standard Javadoc Help provides a couple of extra frames to let you browse packages and classes. The customized Eclipse Javadoc Help contains Eclipse-style XML navigation files rather than those extra HTML frames. The Eclipse-style XML navigation files create the TOC navigation that allows the user to search for a specific package, class or interface. The customized Eclipse Java API reference solution provides navigation manifests for documentation that will be included in the Eclipse help system.

The whole Eclipse platform is developed around the idea of plug-ins. If you want to contribute your help documents to the Eclipse platform, you have to develop a new help plug-in. The plug-in is composed of the HTML and image files, the table of contents file in XML, and the manifest file. The JavaTOC doclet automatically generates the whole Eclipse plug-in structure, including the XML navigation TOC file that is extracted directly from the Java source code.

The JavaTOC doclet is a customized program that also works with the Javadoc tool. The doclet provides increased flexibility that allows you to generate a TOC navigation on top of the Javadoc documentation files.

The JavaTOC doclet is integrated with the DITAdoclet tool for the IBM DITA API specialization that was developed to generate Java DITA (XML) API files for documenting and generating Java API references. The solution also includes the navigation manifests for the Java API reference documentation that will be included in the Eclipse Help system.


Eclipse Javadoc API reference structure generated with standard Javadoc tool

To access standard Javadoc online help in Eclipse, you can select Help > Help Contents on the menu bar. This brings up the online help in its own browser.
In the left pane, there is a tabbed view for table of contents, search, and context-sensitive help links. The below example, Figure 1, shows a standard Javadoc API references structure. It was generated using only the standard Javadoc tool in an Eclipse environment.

Figure 1. Javadoc API references structure
screen capture showing Javadoc API references structure

The extension point of org.eclipse.help.toc identifies this as a plug-in to the help system.

Listing 1. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
 <?eclipse version="1.0"?>

 <plugin>

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

</plugin>
Listing 2. MANIFEST.MF
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Doc Plug-in
Bundle-SymbolicName: org.dita.dost.doc; singleton:=true 
Bundle-Version: 1.0.0
Bundle-Activator: org.dita.dost.doc.DocPlugin
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
 org.eclipse.core.runtime
Eclipse-AutoStart: true

or

Listing 3. 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"/>
  </extension>

</plugin>

Change the plug-in's name, id, version, and provider-name to values appropriate to your project.

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

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 that shown in Listing 2.

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

<toc label="Building DITA output">
   <topic label="API References" href="index.html"/>
</toc>

Where href = "index.html" is the link to the created javadoc api references. If you want that in the right pane to open the documentation without the HTML frames, the link will be href="overview-summary.html".


The standard Javadoc navigation bar does not allow the user to search for a specific package, class or method.
This is how Javadoc tab navigation is organized and described by SUN Javadoc--Figure 2.

Figure 2. Javadoc tab navigation
screen capture showing Javadoc tab navigation

To create a package comment file, you must name it package.html and place it in the package directory in the source tree along with the .java files. Javadoc will automatically look for this filename in this location. Notice that the filename is identical for all packages.

The content of the package comment file is one big documentation comment, written in HTML, like all other comments, with one exception:
The documentation comment should not include the comment separators /** and */ or leading asterisks. When writing the comment, you should make the first sentence a summary about the package, and not put a title or any other text between and the first sentence.
You can include package tags; as with any documentation comment, all tags except {@link} must appear after the description. If you add a @see tag in a package comment file, it must have a fully qualified name.

The SUN Javadoc will generate output originating from four different types of "source" files:
Java language source files for classes (.java), package comment files, overview comment files, and miscellaneous unprocessed files.

Overview
The Overview page is the front page of this API document and provides a list of all packages with a summary for each. This page can also contain an overall description of the set of packages.OBSERVATIONS:
  • Don't forget to write the package level Javadoc in a file named Overview.html. This file should be placed into the root directory where the code files exist. Javadoc is capable of picking up that file and using its contents
.
Package
Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain five categories: Interfaces, Classes, Exceptions, Errors, and Constants.
OBSERVATIONS:
  • Don't forget to write the package level Javadoc in a file named package.html. This file should be placed into the directory where the code files for that package exist. Javadoc is capable of picking up that file and using its contents
.
Class/Interface
Each class, interface, inner class and inner interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
Each summary entry contains the first sentence from the detailed description for that item.
The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
Use
Each documented package, class and interface has its own Use page. This page describes what packages, classes, methods, constructors and fields use any part of the given class or package.
Tree (Class Hierarchy)
There is a Tree (Class Hierarchy) page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces.
Deprecated
The Deprecated API page lists the entire API that has been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
Index
The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
Prev/Next
These links take you to the next or previous class, interface, package, or related page.
Frames/No Frames
These links show and hide the HTML frames. All pages are available with or without frames.

Eclipse Javadoc API reference structure generated using the JavaTOC doclet

The browsable and searchable Java API reference documentation needs are met with a structured information approach such in XML using the Eclipse JavaTOC doclet and Javadoc Help style.

To enable navigation within an Eclipse help plug-in, the Information Developer must provide a table-of-contents (TOC) written as an XML document. The documentation is provided with a collapsible index on the left side, and HTML documentation on the right. The HTML files can be created using Javadoc or IBM DITA Java API specialization.

You can create the TOC manually, or automatically using the JavaTOC doclet. The JavaTOC doclet generates for you the Java API references TOC structure listing the packages and the contained classes and interfaces.

To create the API reference HTML files, you can run the Javadoc tool or use the IBM DITA API specialization solution to author and generate the Java API reference HTML files--Figure 3.

Figure 3. The HTML—Kit editor
screen capture showing the HTML—Kit editor

If you use the JavaTOC doclet, the API reference documentation is both browsable and searchable. The search capability is possible because of the structured information approach (XML) that is used.

One of the positive side effects of using XML to generate the structure of the API reference documentation is that the content will automatically be indexed for search; if you use the standard Javadoc solution to generate the content, it will not be indexed by default for search.


Eclipse Java API reference structure and the TOC generation necessary files

The following listings provide examples of the TOC XML files used to generate the above Java API reference TOC navigation structure. The files can be generated manually or automatically using the JavaTOC doclet. See the download section below to download Java API reference XML TOC examples for Eclipse.

The following listing shows an example of an Eclipse Java API reference plug-in that references one TOC XML file.

Listing 6. plug-in.xml
<?xml version="1.0" encoding="UTF-8"?>
 <?eclipse version="1.0"?>

 <plugin>

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

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

  </extension>

</plugin>

The following listing shows the same example of an Eclipse Java API reference plug-in that references more than one TOC XML file based on Java package structure. When the documentation is viewed, there will be no difference between using the one TOC or multiple TOC XML files approach.

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

You can use the navref and anchor elements, plus the map element's anchorref attribute, to produce integration points in the Eclipse output, where a navigation file is pulled in or attaches itself at runtime. See the Eclipse resources for more information on authoring Eclipse navigation files

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

The primary XML table of contents must have a title (label in Eclipse), in order for that help's table of contents to load.

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 9. 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="doc/org/dita/dost/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="doc/org/dita/dost/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 that the result is what you expected.

In Eclipse 3.2, the entire doc plug-in can be shipped as a single jar file that includes all of the files that would go into the doc.zip file along with the normal plug-in files: manifest.mf, plug-in.xml, plug-in.properties, etc. Before Eclipse 3.2, the generated Javadoc files would be kept in a doc.zip file along with static HTML files and the extension point schema HTML files.

Undocumented code is difficult or impossible to understand, unusable, and unmanageable. JavaToc doclet is a valuable tool. I truly hope this article will help you find some interest in incorporating JavaToc doclet in your project.


Notices

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

"We live today in an age of specialization. The amount of information available in each field of knowledge is so vast that in order to understand and work with it, one must become a specialist. As more and more material knowledge becomes available, the need grows for greater diversification of study and more specialists."

The information provided in this document has not been submitted to any formal IBM test and is distributed "AS IS," without warranty of any kind, either express or implied.
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.


Conclusions

A future article, Eclipse Java API reference structure generated with JavaTOC doclet will describe the process for automatically generating searchable Java API reference documentation (TOC navigation) using the JavaTOC doclet and the Eclipse Plug-in Help system. In the upcoming articles of this series, we will also look more in-depth at the API documentation authoring and generation technology and some of the value-added enhancements from IBM, including the Java DITA API specialization and how it can be used.


Downloads

DescriptionNameSize
Example of API reference without toc navigationorg.dita.dost.user.zip381KB
Example of API reference with toc navigationorg.dita.dost.zip364KB

Resources

Learn

  • 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 Java language takes an integrated approach to API documentation through the Javadoc comment convention. Read David Gallardo's 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.
  • See the "Documenting your project using the Eclipse help system", from IBM developerWorks.
  • Anyone interested in Eclipse will find this learning guide, Eclipse Learning Guide, brimming with helpful pointers and useful links.
  • This article "Centralizing help in Eclipse", demonstrates how to take advantage of the dynamic nature of Eclipse's help and plug-in architecture to allow you to create a centralized help repository. It focuses on how to create an Eclipse plug-in with a help table of contents, how to use the Infocenter to externalize your help files, and how to create a new menu item that allows you to access the centralized help repository right from the Eclipse main menu.
  • Even developers occasionally need to access a help system; and sometimes you want to do it remotely.
    In the article, "Running the WebSphere Studio help system remotely", Angel Vera shows you how to run the WebSphere Studio Application Developer help system.

Get products and technologies

  • 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.
  • Download the Eclipse Platform Plug-in SDK at the eclipse project downloads page.
  • Join the Eclipse Platform community and download the Platform at eclipse.org. At eclipse.org, you'll also find a glossary of terms and descriptions of Eclipse projects, along with technical articles and newsgroups. The Eclipse Platform white paper details the major components and functions of Eclipse.
  • Find more XML resources on the developerWorks XML zone.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

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

 


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

All information submitted is secure.

Choose your display name



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

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

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

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

 


All information submitted is secure.

Dig deeper into Rational software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational, Open source
ArticleID=202104
ArticleTitle=Java API reference documentation
publish-date=03202007