JavaDoc


Table of Contents

1. JavaDoc
2. Installation
3. JavaDoc Usage
3.1. General Format
3.2. Using javadoc To Produce The Output
3.3. @author
3.4. @version
3.5. @param
3.6. @return
3.7. @exception
3.8. @see
3.9. @since
3.10. @deprecated
3.11. More
4. Simple Example
5. References (And Links You May Find Useful)

JavaDoc is a tool which extracts information from a Java source file to create an API. It is specifically oriented toward this kind of documentation. To quote How to Write Doc Comments for the JavadocTM Tool, an API should describe “all aspects of the behavior of each method on which a caller can rely”. One generally uses JavaDoc to document things such as Classes, Interfaces and Methods but one can theoretically use it for anything written in Java by defining custom tags and creating custom DocLets.

JavaDoc is written within the Java source code for a particular project and then the javadoc tool is used to extract the JavaDoc-marked-up sections and create the HTML files that comprise the JavaDoc output.

JavaDoc comes with the J2SE (Java 2 Platform Standard Edition), available from http://java.sun.com/j2se/. You should be capable of following the instructions that come with this to install it; see Configuring A Windows Working Environment and Configuring A Unix Working Environment.

The general format of a JavaDoc marked up section is:

/**
 * This is the description part of the doc comment.
 *
 * Additional details
 *
 * @tag1 Tag Content
 * @tag2 Tag Content
 *   .
 *   .
 *   .
 */
      

Take notice of the spacing used, the tags section must be separated from the description by a single blank line. The content of the comment starts one space in from the left hand edge of the comment. Tag lists may be separated into logical blocks by inserting a blank line. Lines should preferably be below 80 columns in width. New paragraphs can be specified by using the <p> tag.

The first sentence should summarize the overall behaviour of the Class, Interface or Method being described. It should be terminated with a full stop followed by either a space, tab or newline, it may span more than one line. To include multiple full stops in the first sentence, make sure that the ones that do not signify the end of the first sentence are not followed by a space, tab or newline. This can be achieved by using the HTML entity &nsbp;:

 /**
  * This is the part of the first sentence.&nsbp;This is still part of the first sentence. This is not.
  *    
  */
      

One should write from the perspective of the third person:

 /**
  * Correct   - Returns an Integer representing the mean of the numbers provided as parameters.
  *
  *             It has the special feature of blah blah blah...
  *
  * Incorrect - This method returns an Integer representing the mean of the numbers you provide as parameters. 
  *
  *             This has the special feature of blah blah blah...
  */
      

Tag inclusion should accord to the following order:

When using Java code in a description, one should use <code>blah</code>:

*
* Returns <code>true</code> if blah otherwise returns <code>false</code>
*
      

A description may contain any HTML tags:

/**
 * This is the <strong>description</strong> part of the doc comment.
 * <p>
 *   blah blah blah blah blah
 *   blah blah <b>blah</b> <i>blah</i>blah
 * </p>
 * <pre>
 *     blah
 * blah    blah
 * </pre>
 * 
 * @author Ashley <strong>Mills</strong>
 * @version 1.2
 */
public class test {
         .
         .
         .
      

@param parameter-name description

Adds a parameter to the parameter list.

/**
 * Returns the product of two integers.
 *
 * @param int operand one 
 * @param int operand two
 * @return an int 
 */
public int mul(int a, int b) {
   return a*b;
}
      

@see classname

Adds a hyperlink to the section referenced by the classname supplied.

/**
 * Returns the product of the squares of a and b.
 *
 * @see #mul
 *
 * @param int operand one 
 * @param int operand two
 * @return an int 
 */
   public int squaredMul(int a, int b) {
      return mul(mul(a,a),mul(b,b));
   }
      

The classname can be local like this example, prefixed with a hash '#' or a fully qualified class name likejava.lang.String or java.lang.String#charAt.

@deprecated deprecated-text

Marks a class, interface or method as deprecated.

/**
 * @deprecated Replaced by <code>test(int)</code>
 * @see #test(int)
 */
public test() {
}

/**
 * Replaces test().
 */
public test(int i) {
}
      

Here is a simple example showing a few of the features of JavaDoc:

/**
 * Represents a "fuzzy" integer, in that the integer is
 * not exact, but is instead specified as being between a range.
 *
 * @author Ashley Mills
 * @version 1.0b
 */
public class FuzzyInteger {
   private int lowerVal, upperVal;

   /**
    * Creates a new <code>FuzzyInteger</code> object based on the
    * range specified.
    * 
    * @param lowerVal The lowest value that the integer could be.
    * @param upperVal The highest value that the integer could be.
    */
   public FuzzyInteger(int lowerVal, int upperVal) {
      this.lowerVal = lowerVal;
      this.upperVal = upperVal;
   }

   /**
    * Doubles the value of the <code>FuzzyInteger</code>.
    */
   public void doubleFuzzy() {
      lowerVal = lowerVal+lowerVal;
      upperVal = upperVal+upperVal;
   }
}