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:
- Javadoc, a open-source tool created by Sun Microsystems. For more information, read java.sun.com/j2se/javadoc.
- JavaHelp, a help set which has index and search capabilities. For more information, see java.sun.com/products/javahelp .
- Authoring tools from JavaHelp. For more information refer to the list on java.sun.com/products/javahelp/industry.html.
- Standard Java Coding Conventions. For details, see java.sun.com/docs/codeconv and a quick reference sheet.
- Javadoc Conventions. For details, see java.sun.com/j2se/javadoc/writingdoccomments.
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.
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
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
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 = "126.96.36.199" 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".
Standard Javadoc navigation bar organization
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
- 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
- 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.
- 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
- 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.
- 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.
- 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.
- The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
- 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
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 = "188.8.131.52" 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.
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.
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.
|Example of API reference without toc navigation||org.dita.dost.user.zip||381KB|
|Example of API reference with toc navigation||org.dita.dost.zip||364KB|
- 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.
- Find more about the collaboration between the developers and the writers in my "API documentation process series article"
- Find more about the "DITA XML Specialization for Writing Language-conformant Reference Documentation for API libraries".
Dig deeper into Rational software on developerWorks
Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.