On Documentation

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.

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

Here is an partial example of such JavaDoc documentation (without the code): Employee.java.

JavaDoc

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

javadoc [file].java

Here is an example of such a page created from the documentation given above: Employee.html

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 "Payroll Documentation" -link http://java.sun.com/products/jdk/1.2/docs/api/ *.java

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