Next: Public and Private Up: The Frightened Freshers Guide Previous: More Fun With The

Writing Good Documentation

You have no doubt looked at the Java API documentation and have seen that all the Classes follow the same layout with descriptions of the Class, its methods and any attributes that it might have. Would it not be great to be able to have those for Classes that you write? Well you can! There is a program called javadoc which generates documentation for you based on your classes and comments contained within the Class.

To start including javadoc comments, you will need to do the following:
$\begin{lstlisting} /** This Class is designed to show javadoc comments * @autho... ...9/01/2005 public Class someClassHere { someClassHere() { } } \end{lstlisting}$

Thats just a very simple example of class documentation with an author and version as well as a short description of the Class. Methods should also have documentation.

$\begin{lstlisting} /** * An example of a method - replace this comment with yo... ...ample parameter for a method * @return the sum of x and y */ \end{lstlisting}$

As you can see there are keywords with the at symbol before them and then data that you want in this keyword.

One major point to note about javadoc and commenting in general is that it is completely futile and useless to comment after writing a piece of code in a method at the end of a project. Do it as you go along and you will definiately save yourself a lot of trouble. Get into the habit of labelling up odd bits of code that you would not know what it does immediately with comments after the code and in the method javadoc bit too.

Next: Public and Private Up: The Frightened Freshers Guide Previous: More Fun With The

Tom Carlson 2006-01-10