Simple Guide to basic Javadoc

Simple Guide to basic Javadoc

Javadoc tool is in my opinion one of the most underestimated tools available for a Java developer. Recently I have started digging into some opensource projects when looking for a nice examples of design patterns and I was surprised at high quality of their code in terms of commenting. This is something I, and many people I know, forget to do while producing source code every day.
Following the principle to leave the source in a better condition every time we open it in the IDE, I will leave here a simple example of a nice and clean class comment:

(example from JHotDraw)

/**
* Tool to select and manipulate figures.
*

* A selection tool is in one of three states: 1) area
* selection, 2) figure dragging, 3) handle manipulation. The different
* states are handled by different tracker objects: the
* <code>DefaultSelectAreaTracker</code>, the <code>DefaultDragTracker</code> and the
* <code>DefaultHandleTracker</code>.
*

* A Figure can be selected by clicking at it. Holding the alt key or the
* ctrl key down, selects the Figure behind it.
*

<hr />
* <strong>Design Patterns</strong>
*
*

<em>Strategy</em>

* The different behavior states of the selection tool are implemented by
* trackers.

* Context: {@link SelectionTool}; State: {@link DragTracker},
* {@link HandleTracker}, {@link SelectAreaTracker}.
*
*

<em>Chain of responsibility</em>

* Mouse and keyboard events of the user occur on the drawing view, and are
* preprocessed by the {@code DragTracker} of a {@code SelectionTool}. In
* turn {@code DragTracker} invokes "track" methods on a {@code Handle} which in
* turn changes an aspect of a figure.

* Client: {@link SelectionTool}; Handler: {@link DragTracker}, {@link Handle}.
*

<hr />
*
* @author Werner Randelshofer
* @version $Id: SelectionTool.java 718 2010-11-21 17:49:53Z rawcoder $
*/

public class SelectionTool extends AbstractTool{
.................... class source code ..........
}

Some comments on the comment itself:

1. Use

<code>

style for keywords and names.
Keywords and names are offset by

<code>...</code>

when mentioned in a description. This includes:

* Java keywords
* package names
* class names
* method names
* interface names
* field names
* argument names
* code examples

2. add links for API names (listed immediately above) using the

{@link}

tag. It is not necessary to add links for all API names in a doc comment. Because links call attention to themselves (by their color and underline in HTML, and by their length in source code doc comments).

3. User @Code instead of if you have to include some special chars in it eg.

 {@code Outer<S>.Inner<T>}

see the Joseph D. Darcy's Oracle Weblog for more info.

4. Use the @author tag and don't be ashamed of your code :)

See more example of good commenting in JHotDraw project

One response on “Simple Guide to basic Javadoc

Leave a Reply