Javadoc Comments

Javadoc is the Sun Microsystems tool (http://java.sun.com/j2se/javadoc) for generating application programming interface (API) documentation in HTML format from document comments in source code. In the code, you use special comment characters ”starting with /** and ending with */ ”to indicate that the javadoc tool should process the comment to produce HTML-formatted documentation.

Writing javadoc comments can become an entire project in itself, and you need to be thorough because Sun does review code comments. There are several approaches to javadoc commenting. You do not have to worry about it, however. Just be sure to add comments that are enclosed in the multiline comment for every major declaration. The text is written in HTML and must precede a class, field, constructor, or method declaration. These comments are structured as a description followed by special javadoc tags, such as @param , @return , and @see .

Javadoc comments are part of your grade, so don't be shy about commenting your code. Every class and method should be commented in such a way that the javadoc tool can grab it. To see how to do this please refer to Sun's guidelines on writing javadoc comments in code at http://java.sun.com/j2se/javadoc/writingdoccomments/index.html. For detailed reference material on Javadoc tags please refer to http://java.sun.com/j2se/javadoc/index.html#javadocdocuments. The following is an example of how to comment a method that results in proper javadoc documentation:

 /**  * Returns a Blob object that represents a customer.  * The id argument must specify a single customer. The last_name  * argument is a description that will be displayed later.  * <p>  * This method will either return a Blob or a null if the  * Blob doesn't exist.  *  * @param  id        the customer unique identifier  *         last_name the customer's last name  * @return      the customer Blob  * @see         Blob  */  public Blob getBlob(int id, String last_name)  {     try     {             Blob blob = getCustomer(id);             if(blob != null)             {                     blob.setLastName(last_name);                     return blob;             }     } catch (NoBlobException e)     {         return null;     }  } 

You can also check your comments with a tool at Sun called DocCheck. It will give you a report describing style and tag errors in your source code. The home page is http://java.sun.com/j2se/javadoc/doccheck/index.html.