Package Design Checklist, Documentation

1.3.1. Provide a package overview (package.html) for each package

Rationale:

Consistency in Documentation. Javadoc is the standard format for Java reference documentation. Developers expect to find Javadoc description of every single Java construct, including packages. Unlike classes and methods which can be documented using javadoc comments inserted directly into Java source files, you need to create a separate package-info.java (or package.html) file and place it into the package directory. Omitting to provide Javadoc documentation for packages is one of the most common Java documentation mistakes.

1.3.2. Follow standard Javadoc conventions

Rationale:

Consistency in Documentation. Simply follow the Javadoc conventions established by Oracle (Sun).

1.3.3. Begin with a short, one sentence summary of the API

Rationale:

Consistency in Documentation. The Javadoc tool automatically copies the first sentence of the provided package overview to the package summary. Write a clear and informative initial sentence which can stand on its own. Focus on the purpose and intended use of the package. Developers use package summaries to decide which packages are relevant to their current task and which packages can be safely skipped.

1.3.4. Provide enough details to help deciding if and how to use the API

Rationale:

Simplicity and Documentation. Developers will look at a package overview primarily to decide whether the API is worth further investigation. Consequently, a good package overview starts by answering in less than half a page of text the following questions: 1) Can this API solve my problem? 2) What will the solution look like, roughly?

Do this:

package com.company.video.converter;

/**
 * Provides utilities for converting MPEG-1 or MPEG-2 Video, in NTSC or PAL format,
 * into Internet media formats. The following output formats are supported:
 *
 *   - Flash Video (F4V)
 *   - QuickTime multimedia file format (MOV and QT)
 *   - Windows Media Video (WMV)
 *
 *  You can merge several video clips into one and clip multiple segments from a single video.
 *  You can clip, rotate, and flip.
 *  You can adjust brightness, contrast and saturation.
 *  You can add subtitles.
 *
 *  The MPEG input module produces a proprietary intermediate video format (VideoStream)
 *  and you pipe various modules together using VideoStream to produce the desired output.
**/

1.3.5. Indicate the entry points (main classes or methods) of the API

Rationale:

Documentation. Callers rarely need all types from a package. Finding out where to start can be challenging when working with large packages. Nobody likes wasting time inspecting types they won’t need. Indicate (and also link to) the most important or most frequently used type(s) callers should explore first in the Javadoc package overview.

1.3.6. Include sample code for the main, most fundamental use case

Rationale:

Documentation. A line of code is worth a thousand words. When encountering an unknown API, the developer’s first question is how to get it working. Sample code for the simplest, most fundamental use case included in the package overview section of the Javadoc answers this essential question.

1.3.7. Include a link to the Developer Guide

See item 1.3.8 below.

1.3.8. Include a link to the Cookbook

Rationale:

As we discussed in “Writing helpful documentation” , reference documentation like the Javadoc is rarely sufficient. For all but the simplest of APIs, we need other forms of documentation, such as developer guide or cookbook. These are best kept separate from the frequently-referenced Javadoc, but their content linked to from where it is appropriate. At a very minimum, package overviews should contain links to these materials. Links to relevant sections can be also provided from class and method overviews where needed.

1.3.9. Indicate related APIs

Details coming soon…

1.3.10. Include the API version number

Rationale:

Evolution. A change in minor version number indicates backwards-compatible API extensions and enhancements, while a change in the major version number indicates an extensive API overhaul which may include non-backwards compatible changes. Modifications are typically required in existing clients to make them work with a new major API version, hence the importance of including the @version tag indicating the version number into the package overview section of the Javadoc.

1.3.11. Indicate deprecated API versions with the @deprecated tag

Details coming soon…

1.3.12. Consider including a copyright notice

Rationale:

Both the API itself and the associated documentation, including the Javadoc, represent intellectual property which need legal protection in multiple jurisdictions. Including the appropriate copyright notice into the package overview section of the Javadoc may be a legal requirement. Talk to your manager or contact the legal department of your organization for advice and to obtain an approved copyright notice.

1.3.13. Avoid lengthy package overviews

Details coming soon…

1.3.14. Do not include implementation packages into published Javadoc

Details coming soon…

 

This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 Canada License.