Javadoc

This page discusses - Javadoc

Javadoc

Javadoc

     

Sun Microsystems has provided a computer software tool known as Javadoc. This tool is used to generate API documentation into HTML format from Java source code. It is interesting to know that Javadoc is the industry standard for documenting Java classes.

 Javadoc is a program that is already included in JDK. We can use Javadoc to run over the source code to produce documentation of our classes in the HTML files . We have to tag our code with by using some comment formats to use javadoc tag on our source code. For instance Javadoc comments looks like this:

NOTE : To start a Javadoc comments use /** to start, and */ to end, and use tags such as @param, @return, and @exception in between to describe the workings of a method.

The format is given below to use the Javadoc comments:
/**
* Summary of the sentence.
*  information about the
* program, class, method or variable 
* then the comment, using as many lines
* as necessary.
*
* zero or more tags to specify any type
* of information, such as parameters and return
* values for a method
*/

Start with comment delimiter (/*) followed by another (*). The next line starts with an asterisk and write as many line as you want starting with an asterisk. The last line ends with the delimiter (*/). The first sentence to start with is a "summary sentence" showing the description of the program, class, method or variable. We can write few more lines if required, but not any blank lines. After writting the general description, a sequence of tags follows leaving a blank line.
Use different tags to display different situations. The example below shows a Javadoc comment without tags that describes the variable declared immediately below it:

/**
* The number of employees in a company. This variable must not be
* negative or greater than 200.
*/
public int numEmployees;


One interesting thing to know about Javadoc comments is that we can embed HTML tags to format the text. For example:

/** 
* <B>Java declaration</B> 
*/ 

Lets have a look on Javadoc tags

 Tag   Description
 @version   Shows the version number of a class or method.
 @author   Shows the Developer name
 @return   Documents the return value. This tag should not be used for constructors or methods defined with a void return type.
 @deprecated  Marks a method as deprecated. Some IDEs will issue a compilation warning  if the method is called. 
 @see   Documents an association to another method or class.
 @param   Defines a method parameter. Required for each parameter.
 @throws   Documents an exception thrown by a method. A synonym for @exception   introduced in Javadoc 1.2.
 @since   Documents when a method was added to a class.
 @exception   Documents an exception thrown by a method ? also see @throws.
 private  Displays all classes and members
 use  It creates class and package usage pages
 Windowtitle  It shows the window title of the document
 Header  It includes for header text of the page
 Footer  It includes footer text for the page  
 Bottom  It includes bottom text for the page
 Package  Shows package classes and members
 Protected  shows protected classes and members
 Classpath  Helps to find user class files
 noindex  doesn't provide the index
 nohelp  doesn't provide the help link
 notree  doesn't provide class hierarchy

 To document source code developers use certain commenting styles and Javadoc tags. A Java block comment starting with /** will begin a Javadoc comment block This comment block will be included in the HTML. Some tags are provided in the above table which begins with an "@" (at sign).