Javadoc is a useful tool that helps give a better understanding of code written. The Java API documentation acts as a guide of how to use all Java defined classes, interfaces, etc. Javadoc is a tool that allows the same kind of documentation to be automatically generated if proper Javadoc comments are written. The Java API documentation is actually a result of using the Javadoc tool. Overall, the Javadoc tool can give a professional looking html documentation of Java files written at ISIP.

Basics:

All Javadoc comments are placed directly above what it is describing. Every Javadoc comment starts out with the characters "/**" and is closed with the characters "*/". Every line in between needs to begin with a '*' character. The first line after the "/**" must be a description. Regular sentancing is used to give the description. The description follows standard html text format. This may be useful if a link maybe necessary.

The rest of each Javadoc comment are of Javadoc tags. The same tag may have to be used multiple times to give a listing of paramaters a method has. If this is the case, the tags must be placed on consecutive lines. Below is a list of a few tags.

	 @author
	 @exception
	 @link
	 @param
	 @return
	 @see
	 @throws 	//same as @exception

Classes:

Classes and Interfaces start out with a description as all Javadoc comments do. Then an author tag and a version tag might be used. As hinted at in the name, the author tag has information about the author. The author's name, home page, and email address can be given in consecutive author tags. The version tag can be used to keep track of the version of the software. Much of the time just a class description without these two tags will do.

	Ex:
	 /**
	  * Implements the circular buffer producer/consumer model for any java
	  * object
	  */

Variables:

Variables and constants just need to have a description.

	Ex:
	 /**
	  * Index of the first object avaiable to read
	  */

Constructors:

Javadoc comments for constructors include a description and the parameters of the constructor. The "@param" of the parameter tag is followed by the name of the parameter and the textual description of the parameter.

	Ex:
	 /**
	  * Detailed description of constructor below
	  *
	  * @param size_a Parameter description.
	  * Description can carry over to next line.
	  */

Methods:

In addition to parameter tags, methods can have a return tag and exception or throws tags. Return tags are only necessary if the method returns an object as throws tags are needed only if an exception may occur. The "@return" is followed by a textual description of what the method returns. The "@throws" is followed by the type of exception and the textual description of how that particular exception can be thrown.

	Ex:
	 /**
	  * Detailed description of method.  This method returns the number
	  * objects skipped when the skip method is called.
	  * 
	  * @param n_a The number of Objects to skip
	  *
	  * @return The number of objects actually skipped
	  * 
	  * @throws IllegalArgumentException if n_a is negative
	  * @throws InterruptedException if the thread is interrupted while
	  * waiting
	  */

See and Link Tags:

See and link tags can be used to provide links to other parts of the documentation or a link to anywhere on the web. The "@see" is followed by the link or url. The see tag adds a small section after all other attributes entitled "See Also:" which has a link available to click.

The link tag is the same as the see tag except it is encased by '{' and '}' characters. The link tag can be placed in the textual descriptions of any part of the class.

	Ex:
	 /**
	  * The default size for a circular buffer object
	  * @see file_directory
	  */

The link and see tags are not as common as the other tags described above at ISIP.

Compiling Javadoc:

Once all the Javadoc comments have been added to a source file, the file needs to be compiled with a different compiler. Use the "javadoc" command to call the Javadoc compiler. This generates html files similar to those found in the Java API documentation. Most commonly there will be many classes involved in a project. Then logically the files will be compiled by "javadoc *.java". Multiple html files are made. Mainly, an index file is created linking all the class pages together. There are other pages created dealing with constants, class hierarchies, packages, etc.

Compiling improper javadoc comments can produce errors and warnings just as compiling improper regular java code. However, javadoc errors and warnings are much simpler to correct. The most common error occurs when the class of a file is not given a public or protected modifier. Note that private classes would not need any java style documentation because they are internal and not for the public to know about. Warnings are a result of improper syntax. If the above syntax is followed, this will not be a problem.

Go to previous page
Go to next page