![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
Introduction to API documentation
Typically, the Javadoc tool from Sun® Microsystems is used to generate Java™ API reference documentation from source code. The Javadoc tool helps by generating the basic structure of the Java API reference documentation, but the documentation is often incomplete and limited to information from the developer comments. The responsibility for elucidating the developer comments and providing fully documented API reference documentation falls on the API writer.
A fully documented API can serve several purposes, but the most important reason is to allow users of the API to fully understand the API functions that are available to them. For users to completely use the functionality of the API, they require an accurate and fully documented API.
This article describes a process for generating Javadoc API documentation using directly updated Java source code, IBM Rational® ClearQuest® (hereafter, ClearQuest), and ClearCase.
- Assumptions
- Requirements
- Process: JavaDoc with Directly Updated Source
- ClearCase Process Graphic
- ClearCase-Based Procedure
- Pros
- Cons
- Process-specific issues and considerations
- See the Resources section for a link.
The process described in this article is based on the following assumptions. In some situations, the specifics may be different and so the process might differ.
- The development team is responsible for writing the original comments and maintains the Java source code updates.
- The API writer monitors the public packages that are added or removed.
- The API writer monitors the development delivery notices. Developers will include the appropriate information in the "Impact on Doc" section. This section will indicate any public API packages and classes that have been changed.
- The API writer provides Javadoc suggestions to the development team such as required comments, tags, style, etc.
- The development team is responsible for reviewing the edits and the final source code.
- The build team generates the Javadoc files for release.
The following requirements were agreed upon before the process was developed:
- The reference file listing the API packages that need to be documented and included in the build needs to be updated by the development team.
- The API writer creates a view on the Product Integration Stream (PIS) and delivers the changes directly to this stream.
Process for creating Javadoc API documentation with directly updated source
The process uses ClearCase to update the source code from which the Javadoc documentation is generated. The procedure uses ClearQuest to track the final Javadoc updates and the delivery to the build. In ClearQuest, the developer opens a defect and assigns it to the appropriate API writer. The API writer resolves the defect when the last changes are delivered to the PIS. The general workflow for this process is shown in the following graphic.
Figure 1. ClearCase Process Graphic
- 1. The API writer joins the PIS development project by creating a view on this stream.
- The reference file listing the API packages that need to be documented is used to know what needs to be documented. The file lists the public packages that are going to be delivered to the build and need to be documented. If a package is not mentioned in the file, Javadoc is not generated for the package.
- 2. In ClearCase, the API writer rebases and gets the latest source code files for the local Writer Development Stream (WDS).
- ClearCase reports list the changes since the last rebase. The report also allows the API writer to verify that the previous documentation changes were delivered and properly merged.
- 3. The API writer documents the public Java classes and edits the developer Java source code comments in WDS.
- 4.In WDS, the developer checks that the content of the delivery builds correctly.
- Provides technical review of the content to the API writer.
- 5. The API writer enters the edits, checks in and delivers the final Java source code files to the PIS stream.
- 6. The product build team generates the Javadoc from the latest PIS source code delivery.
- 7. The API writer ports their changes to any additional streams required to support parallel development of the components following the same process.
Regardless of how the source-code files are handed off between the teams, this process for directly updating the Java source code has the following positive aspects:
- Eliminates the need to copy source files back and forth between developers and writers.
- Ensures that the latest source is always being used and is easily accessible.
- Ensures that a clear audit trail exists for changes.
- Ensures that the changed files build correctly before delivery to the build.
- Ensures that the API writer knows which packages need to be documented.
- Reduces duplication of effort as developers see the writer additions in their source code files.
- Ensures that the API writer updates are incorporated in the API source code files correctly and in a timely manner.
- Ensures that the API writer is notified of updates to previously documented files.
- Ensures that the API writer is notified of public API changes as they occur.
This process for directly updating the Java source code has the following negative aspects:
- Some API writers may be unfamiliar with editing and delivering the Java source code directly to the product integration stream.
Process-Specific Issues and Considerations
- ClearCase is used to track each of the steps listed above - the delivery of the edited source code to developers and the delivery of the Javadoc HTML files to the Help build.
- ClearQuest is used to track the final Javadoc updates and the delivery of the Javadoc to the Help build.
Learn
- Creating Javadoc API documentation with indirectly updated source is the first article in this API documentation process series.
- 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.
- The Javadoc doclet API lets you write custom Javadoc plug-ins to produce different forms of documentation, or even auto-generate code or schemata from Javadoc comments.
- The Sun tutorial How to Write Doc Comments for the Javadoc Tool describes the rules and philosophy of Javadoc.
- Stay current with developerWorks technical events and webcasts
- Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products.
Get products and technologies
- Build your next development project with IBM trial software, available for download directly from developerWorks.
Discuss
- Participate in developerWorks
blogs and get involved in the developerWorks community.
-
Rational forums: Ask questions about IBM Rational products.
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.
Don Weinand is a Senior Software Engineer for IBM Software Group, Rational Software development team. He has been with IBM since the Rational acquisition in 2003. As part of the IBM Rational division of the IBM Software Group, Don has contributed to the J2SE modeling component for the IBM Rational XDE product as well as the RAS tooling in the Rational Software Architect and Rational Software Modeler products.
