Documenting « Development « Java Articles

Concurrency is a new and complex concept for many developers and, at best, is an old and complex topic for experienced concurrent programmers. The end result is that if you use the concurrent programming features of the Java programming language, then you need to document them thoroughly. Doug Lea (see Concurrent Programming in Java in Resources) suggests that when a class includes both synchronized and unsynchronized member functions, you must document the execution context that a member function relies on, especially when it requires unrestricted access to allow other developers to use those member functions safely. When a setter (a member function that updates a field) of a class that implements the Runnable interface is not synchronized, then you should document your reasons why. Finally, if you override or overload a member function and change its synchronization, you should also document why.

This page contains links to the documentation for the Autonomic Computing Toolkit. All of this documentation is also available in the Autonomic Computing Information bundle, which you can download. Please send any feedback you have on the documentation to [email protected].

I don't often run across developers who tell me they like writing documentation for their software-development projects. Unless you never expect to leave your project, will always be the lone developer, or have no users ? probably not good signs for a project ? you need a semipermanent way to communicate the software's purpose to others. Some developers misconstrue the Agile Manifesto's "Working software over comprehensive documentation" statement to mean that no documentation is necessary (see Resources). On the other hand, you don't need to burden users or other developers with unnecessary documentation. I typically look for the happy medium. You guessed it: This article shows you how automation can streamline the process (and reduce the misery) of generating project documentation.

Design Markers are Marker Interfaces that are used primarily for documentation purposes and specifically to document Design Choices. The description of each design choice is placed in the JavaDoc comments of its associated design marker interface in as much detail as desired.

The Javadoc Tool was originally designed to generate API documentation from Java source code. Now, it is not only a documentation generator, but an an extensible engine for processing Java source code. This article illustrates how to write programs for the Javadoc Tool.