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

A bridge between writer and developer

The process described in this article is the result of discussions and experimentation by development and documentation teams. These teams recognized that quality application programming interface (API) reference documentation must be a collaboration between the developers and the writers. In addition, the teams sought to have all documentation updates be reflected back into the source code and to have daily Javadoc builds for internal customers include updated documentation. The teams wanted a process that was efficient and reduced duplication of effort.

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

David Steinmetz (dsteinme@us.ibm.com), Sr. Technical Editor, Rational software, IBM

Davis SteinmetzDavid Steinmetz is a senior technical editor and program manager for Rational software in the Software Group at IBM, and he previously edited at Microsoft and DEC/Compaq. He is a member of the corporate editing council and leads the effort to create corporate API reference style guidelines. David helps to create editing strategies for DITA content and he presented on this subject at the 2005 Content Management Strategies conference. David is a senior member of the Society for Technical Communication and was a reviewer of IEEE Std. 2001-1999, IEEE Recommended Practice for Internet Practices.



Janis Steinfeld (jlsteinf@us.ibm.com), Manager, Rational software, IBM

Janis SteinfeldJanis Steinfeld has a BA History/Biology Rice University, MS Health, Physical Education, Recreation North Texas State University, BS Computer Science Florida Atlantic University, and 18 years as a technical writer and documentation manager with Encore Corporation, Verdix, Rational and IBM. For the last 10 years, Jan have managed a distributed team responsible for a variety of model-driven development environment projects running on Windows, Linux, and Unix. She managed the development from scratch of an extensive HTML-based online help system for Eclipse and VS.NET. Most recently, her team has moved to DITA XML and provides ID deliverables for the IBM Rational Software Desktop products.



25 April 2006

Introduction to API documentation

writer-developer

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 indirectly updated source code and IBM Rational® ClearQuest® (hereafter, ClearQuest), and IBM Rational® ClearCase® (hereafter, 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.

  • All parties agree that it is a goal that complete documentation be included in the API source files as Javadoc comments.
  • The documentation team will provide Javadoc requirements to development teams early in the process. This will cover required tags, style, and wording examples.
  • Development teams are responsible for writing the original comments in source code and maintaining the source code comments.
  • Writers will access a copy of the API source code files; therefore, developers are responsible to merge in documentation additions and changes to the Javadoc comments.
  • As development teams are developing and documenting their APIs, the documentation team will be involved or leveraged for feedback and questions.
  • The Information Development (ID) team will be responsible for ensuring that updated Javadoc API documentation is available within the online help system and updated regularly.
  • A single API development contact will be provided. This contact is responsible for merging in the source code edited by documentation and reviewing these edits.

Requirements

The following requirements were agreed upon before the process was developed:

  • We need a clearly defined process by which writers obtain stable source files and then return them for incorporation in a timely manner.
  • We need a clearly defined process to ensure that a writer’s updates are incorporated in the API source files correctly and in a timely manner.
  • We need a clearly defined process by which writers are notified of updates to previously documented files.
  • There will be regular meetings and communication processes established between developers and ID personnel working on the API documentation.
  • File names must be consistent and predictable. This will help the writers who are creating links to the Javadoc API documentation.
  • If a ClearCase-based procedure is used, rebase by the documentation team from the Product Integration Stream should be configured to pick up only the public APIs. In addition, the ClearCase change report should be limited to public APIs.

Process for creating JavaDoc API documentation with indirectly updated source

The general workflow for this process is shown in the following graphic. The source-code handoffs (green arrows) can be accomplished in two ways:

  • Using e-mail and .zip files. See "E-mail-based procedure."
  • Using ClearCase (CC). See "ClearCase process graphic" and "ClearCase-based procedure."


In both procedures, ClearCase is used to control the development stream. The choice of procedure will be determined by the size and complexity of the API to be documented. Note that both procedures use ClearQuest (CQ).

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

This graphic shows the workflow for the source code (green arrows) and the Javadoc builds generated from the source code.

Figure 1. General Workflow Graphic
The Java Beans view

E-mail-based procedure

The procedure that depends on e-mail instead of ClearCase for the handoff of files cycles through steps 1-6 until the final Javadoc HTML files are generated.

Note: During this process, the daily build also generates new Javadoc HTML files that are included as part of the overall code package delivered to internal customers.

  • 1. Developers generate and make available to the documentation team the Java source code public packages containing the commented classes and methods. In parallel, a set of Javadoc HTML files is also generated and made available to the documention team as part of the standard build process.
    • In ClearCase, a developer delivers from the developer's development stream to the product integration stream.
    • In ClearQuest, the developer opens a defect and assigns it to the appropriate writer. Granularity is per feature, with each new or modified package listed in the defect.
  • 2. The technical writer reviews the Javadoc HTML files and then documents the public Java classes and edits developer comments in local version of the Java source code. All editing occurs within comments.
    • In ClearQuest, the writer sets the defect to Active. If the defect has come back for verification, there are no new changes or updates to be made, and the writer input has been successfully merged, the writer closes the defect within one week.
  • 3. The technical writer generates the Javadoc HTML files for inclusion in the product build and submits the files to the help project.
    • In ClearCase, the writer submits the Javadoc help files to the help project.
    • The technical writer is responsible for making sure all necessary files and processes are in place for these files to appear in the appropriate location in the online help system.
  • 4. The technical writer submits the edited copy of the Java source code to developers.
    • The writer creates a .zip file of the source code and sends an e-mail message to the API development contact.
    • In ClearQuest, the writer updates the defect and reassigns it to the API development contact (the details depend on granularity of defect).
    • The writer will complete this work within 1 week of receiving the package unless otherwise arranged with the development team
  • 5. The development API contact merges this copy of the source code with the original source code, with all changes confined to comments.
    • In ClearCase, the API development contact merges changes into the product integration stream. The writer is notified of delivery.
    • In ClearQuest, the API contact resolves the defect and reassigns it back to the writer for verification.
    • Development will complete this merge within 1 week of receiving the updated file(s), unless otherwise arranged with the writer.
    • If developers have questions about any of the edits, they will contact the writer for clarification. If the writer does not hear from the developer, the assumption is that all edits have been accepted and merged.
  • 6. Developers synchronize to the latest version of the source code and make their changes.
    • In ClearCase, a developer rebases from the product integration stream.
    • The process continues at step 1.

ClearCase process graphic

This graphic shows the additional ClearCase integration stream used to control the documentation version of the source-code files and the process used as the source code is revised.

Figure 2. ClearCase process graphic
Process Graphic

ClearCase stream configurations:

Abbreviations

CC -- ClearCase
CQ -- ClearQuest
DIS -- Documentation integration stream
PIS -- Product integration stream
DDS -- Developer development stream
WDS -- Writer development stream

  • Each developer has a developer development stream (DDS) associated with the product integration stream (PIS).
  • A dedicated ClearCase integration stream is created for the documentation team, the documentation integration stream (DIS). This stream is a substream of the PIS used by developers.
  • Each writer has his or her own development stream associated with the DIS, the writer development stream (WDS).

ClearCase-based procedure

This procedure uses ClearCase processes to move source code between the development and documentation teams, and it cycles through steps 1-6 until the final Javadoc HTML files are generated.

Note: During this process, the daily build also generates new Javadoc HTML files that are included as part of the overall code package delivered to internal customers.

  • 1. Developers generate and make available to the documentation team the Java source code public packages containing the commented classes and methods. In parallel, a set of Javadoc HTML files is also generated and made available to the documentation team as part of the standard build process.
    • In ClearCase, the developer delivers from the developer development stream (DDS) to the product integration stream (PIS).
    • In ClearQuest, the developer opens a defect and assigns it to the appropriate writer. Granularity is per feature, with each new or modified package listed in the defect.
  • 2. The technical writer reviews the Javadoc files and then documents the public Java classes and edits developer comments in forked version of the Java source code. All editing occurs within comments.
    • In ClearCase, the documentation team representative rebases the documentation integration stream (DIS), the technical writer rebases the writer development stream (WDS) and works in the WDS version. The ClearCase report lists changes since the last rebase. This report also allows the writer to verify that previous documentation changes were merged properly.
    • In ClearQuest, the writer sets the defect to Active. If the defect has come back for verification, and there are no new changes or updates to be made and writer input has been successfully merged, the writer closes the defect within 1 week.
  • 3. The technical writer generates the Javadoc files for inclusion in the product build and submits the files to the help project.
    • In ClearCase, the writer submits the Javadoc help files to the help project.
    • The technical writer is responsible for making sure all necessary files and processes are in place for these files to appear in the appropriate location in the online help system.
  • 4. The technical writer submits the edited copy of the Java source code to developers.
    • In ClearCase, the writer delivers the edited source to the DIS, and the writer or documentation team representative alerts the API development contact.
    • In ClearQuest, the writer updates the defect and reassigns it to the submitting developer (details depend on granularity of defect).
    • The writer will complete this work within 1 week of receiving the package unless otherwise arranged with the development team.
  • 5. The development API contact merges this copy of the source code with the original source code, with all changes confined to comments.
    • In ClearCase, the API development contact delivers from the DIS to the PIS. The documentation team is notified of delivery to the PIS.
    • In ClearQuest, the API development contact resolves the defect and reassigns it back to the writer for verification.
    • Development will complete this merge within 1 week of receiving the updated file(s), unless otherwise arranged with the writer.
    • If developers have questions about any of the edits, they will contact the writer for clarification. If the writer does not hear from the developer, the assumption is that all edits have been accepted and merged.
  • 6. Developers synchronize to the latest version of the source code and make their changes.
    • In ClearCase, the developer rebases the DDS from the PIS.
    • The process continues at step 1.

Pros

Regardless of how the source-code files are handed off between the teams, this process for indirectly updating the source code has the following positive aspects:

  • The API Java source code contains all of the API documentation.
  • The Javadoc HTML files reflect both writer input and developer comments, without requiring direct writer access to the source code and with minimal developer effort to merge in writer edits.
  • The technical writing effort does not interfere with the developer’s access to the source-code files.
  • Developers and writers are able to compare files for new additions and comments (note that this is not automated).
  • It relies on a simple generation process using known tools: Javadoc.
  • Because the API documentation comes directly from the source code, without later revision and reformatting, the tools generate Javadoc-style HTML.

Cons

This process for indirectly updating the source code has the following negative aspects:

  • It depends on developers merging in all writer updates before the next handoff is generated, or changes will be lost.
  • Developers may not understand or accept technical writing changes that are to be merged back in.
  • Source code and the comments may change without notice.
  • It depends on the development team for a number of tasks: generation of the source-code packages, generation of Javadoc HTML files, merges, and text changes.
  • The writer must manually compare old and new versions to discover changes (this is not automated). However, a list of changed files is a ClearCase feature.
  • Due to reliance on the Javadoc tool, we cannot add tables or code examples to the documentation. We are limited to Javadoc capabilities.
  • Some writers may be unfamiliar with editing Java code directly.

Process-specific issues and considerations

The following issues and considerations should be considered if this process is used:

  • Comment merging must be a priority for developers. If it does not happen in a timely manner, then this process is no longer viable. The minimum benchmark is proposed as weekly.
  • We must have a means to track each of the steps listed above—delivery of source code and Javadoc HTML files to the writer, the delivery of edited source code to developers, the delivery of Javadoc HTML files to the help build, and the merging of source code comments.

General issues and considerations

These concerns are relevant even if the teams do not choose to use the process described in this article. This list is not complete.

  • A unified development and documentation schedule must be created that allows quality, on-time delivery of API documentation.
  • Development must provide a list of the API public packages and classes that are to be documented. This list helps with documentation planning.
  • To keep current, we need timely generation of the initial source code packages and revised packages after each merge.
  • Complete developer code comments will provide useful seed material for the API documentation.

Resources

Learn

  • 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

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=109138
ArticleTitle=API documentation process series: Creating Javadoc API documentation with indirectly updated source
publish-date=04252006