The javadoc tool, Java Documentation Comments

The javadoc tool is a documentation generator for the Java language created by Sun Microsystems for generating API documentation in HTML format from Java source code.

The HTML format is used for adding the convenience of being able to hyperlink related documents together so by just clicking on a link user can access the particular documentation page.

The javadoc tool parses the declarations and documentation comments( /** */) in a set of Java source files to produce a corresponding set of HTML pages describing (by default) the public and protected classes, nested classes (but not anonymous inner classes), interfaces, constructors, methods, and fields.

To know more about the Java documentation comments visit Java comments page.

Syntax:

javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpackages pkg1:pkg2:... ] [ @argfiles ]

Arguments can be placed in any order.

The javadoc tool options

These can be any valid command-line options supported by javadoc tool.

packagenames

A list of name of packages, separated by spaces, such as java.lang java.lang.reflect java.io. Each package must be specified if you want to use it. Wildcard characters are not allowed; use -subpackages for recursion. The Javadoc tool uses -sourcepath to look for these package names.

sourcefilenames

A series of java source file names, separated by spaces, each of which can begin with a path and contain a wildcard such as asterisk (*). The Javadoc tool will process every file whose name ends with ".java", and whose name, when stripped of that suffix, is actually a legal class name.

-subpackages pkg1:pkg2

Generates documentation from source files in the specified packages and recursively in their subpackages. An alternative to supplying packagenames or sourcefilenames.

@argfiles

One or more files that contain a list of Javadoc options, packagenames and sourcefilenames in any order. Wildcards (*) and -J options are not allowed in these files.

javadoc tool example

/**
*
* The FirstJava program is developed to just show how to use
* the java documentation comments
*
* @author  Pandurang Wavre
* @version 1.0
* @since   1.1 
*/
class DocClass
{
 // main() method
public static void main(String[] args)
{
// Prints Welcome Java 
System.out.println("Welcome Java");
}
}
 

Creating Documentation for Java Program

D:>javadoc FirstJava.java

This will create few files including FirstJava.html, index.html, etc.

Java Documentation tags supported by javadoc tool

Tag & Parameter	Usage
@author Pandurang Wavre	Describes an author.
@version version	Provides software version entry. Use maximum one per Class or Interface.
@since since-text	Describes when this functionality has first added to the package version. And not the date.
@see reference	Provides a link to other element of documentation.
@param name description	Describes a method parameter.
@return description	Describes the return value.
@exception classname description @throws classname description	Describes an exception that may be thrown from this method.
@deprecated description	Describes an outdated method.
{@inheritDoc}	Copies the description from the overridden method.
{@link reference}	Link to other symbol.
{@code literal}	Formats literal text in the code font. It is equivalent to {@literal}.
{@literal literal}	Denotes literal text. The enclosed text is interpreted as not containing HTML markup or nested javadoc tags.