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).