On Documenting with JavaDoc

Documentation is the bridge between the general specifications for your program and the actual code. You should document your code either before or while you write it, not as an afterthought.

Using JavaDoc comments (/**   */) you should include at least:

• A description of each class, including author and version/date.
• A description of each method, including acceptable arguments, return values, global variables affected, exceptions thrown, and what the method does.
• A description of any public variables.

When documenting a class or method, describe what it does or what it models. Do NOT describe how it does this--the details of your specific implementation.

You only need to use @tags (such as @param, @return, @exception) if the method actually has parameters, returns a value, or throws an exception.

You should also use implementation comments (/*   */ and //) to comment on tricky or confusing sections of code.

JavaDoc

When you're done writing your code, you can type:

javadoc [file].java

The javadoc tool takes a number of command line arguments. Some of the more useful ones are:

• -private -- document all classes and methods
• -package -- document all classes and methods except private ones.
• -d <directory> -- puts docs in a certain directory (needs to exist first)
• -author -- includes @author tags
• -version -- includes @version tags
• -window-title -- adds a title for your documentation
• -link <url> -- will update links to point to documentation of standard classes at <url>. (You must be connected for this to work, as it checks the package-list at the URL).
• -help -- learn more of these arguments

So, an example javadoc command is:

javadoc -author -version -package -d docs -windowtitle "Assignment 1 Documentation" -link http://java.sun.com/j2se/1.3/docs/api/ *.java

You can learn more about JavaDoc in general and How to Write JavaDoc Comments directly from java.sun.com.