API documentation process series: Creating Javadoc API documentation with directly updated source

The article describes the generation of Javadoc documentation using a directly updated source code in IBM Rational® ClearCase® (hereafter, ClearCase). The process described in this article is the result of discussions and experimentation by development and documentation teams. The proposed API reference documentation process streamlines the process for generating public API Javadoc documentation for applications. The process resolves the need to copy source code files back and forth between developers and the API writer. It also ensures that the latest source code is always being used and updated. As a result, the generated Javadoc HTML files will reflect both writer input and developer comments with minimal developer effort to merge in the API writer edits. Also, the Javadoc builds for internal customers will include the most complete documentation possible, because all documentation updates are reflected back into the source code.

Share:

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

Don Weinand (dmweinan@us.ibm.com), Software Engineer, IBM Software Group, Rational Software

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.



09 May 2006

writer - developer

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.

Note that you do not need to be a programmer to participate in the API documentation process. If you would like to contribute to the process with articles, tutorials that can improve the API documentation, we would like to hear from you.


Assumptions

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.

Requirements

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.

ClearCase Process Graphic

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

Figure 1. ClearCase Process Graphic
Process Graphic

ClearCase-Based Procedure

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

Pros

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.

Cons

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.

Resources

Learn

Get products and technologies

  • Build your next development project with IBM trial software, available for download directly from developerWorks.

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 Java technology on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Java technology, Rational
ArticleID=110481
ArticleTitle=API documentation process series: Creating Javadoc API documentation with directly updated source
publish-date=05092006