Thomas A. Alspaugh
Javadoc

Introduction

javadoc is a command-line tool for extracting special comments (called doc comments) from java source files and generating an easy-to-use HTML file tree containing them.

The java source files need not be complete; they only need have the signature for each method (return type, method name, parameter names and types, throws list), the method bodies can be empty. Fields that are to appear in the javadoc must be complete (type and attribute name). The javadoc will then contain information for all the doc comments that are present—a complete set would comprise class/interface doc comments, field doc comments, and constructor and method doc comments. Thus you can generate complete javadoc documentation using only skeleton java files.

Doc comments begin with /** and immediately precede a class, interface, constructor, method, or field definition are extracted and processed. The comments can include standard HTML markup and javadoc @tags.

The Java API Specification is an example of what javadoc produces.

The javadoc tool is part of the free Sun SDK distribution.

Javadoc organization

The HTML output generated by javadoc is organized like java source is:

Overview and package summaries

Overview documentation: the overview file

The overview file for the output from a javadoc compilation can appear in a file of any name; the file name is specified in the -overview option to the javadoc command.

The file may contain HTML elements and inline {@tags}, and may conclude with one or more:

The file should begin with an HTML <body> tag and end with an HTML >/body> tag.

Package documentation: the package.html file

The summary describing a package must appear in a file named package.html in the package directory along with the java files for the class.

The format of the package.html file is the same as that of the overview file.

Doc comments

Doc comments describe classes, interfaces, fields, constructors, and methods.

Syntactic form

Each doc comment consists of:

  1. /**
  2. an optional main description consisting of text that may contain HTML and inline {@tags} but no block @tags
  3. zero or more javadoc block @tags
  4. */

Text in the description and tag blocks can contain HTML format elements.

A doc comment may be all on one line: 
  /**  All on one line -- but still a doc comment.  */
or span several lines: 
  /**
    Spans several lines --
    still a doc comment
  */
The second and later lines of a multi-line doc comment 
  /**
   *  For that 'retro'
   *  FORTRAN look.
   */
may begin with whitespace and an asterisk, which javadoc discards.

The essential first sentence

The first sentence of each class, interface field, constructor, and method doc comment is reused in the indexes, so this sentence should summarize the thing described, concisely but completely.

The recommended grammatical form for the first line of the doc comment for class X is 'An X is …' or an equivalent sentence.

The recommended form for a constructor or method is that it begin with a verb and be the completion of a sentence that would begin 'This constructor …' or 'This method …', respectively.

For example, the java.lang package and java.lang.String doc comments begin:

package 'Provides classes that are fundamental to the design of the Java programming language.'
class 'The String class represents character strings.'
constructor 'Initializes a newly created String object so that it represents an empty character sequence.'
method 'Returns the character at the specified index.'

Class and interface doc comments

The doc comment describing a class or interface must appear immediately before the class or interface. Its first sentence should summarize the class or interface concisely but completely; a good form for class or interface X is 'An X is a …', 'An X represents a …', or 'A …' or 'Represents a ….' It may include inline {@tags} and may conclude with one or more:

Field doc comments

The doc comment describing a field must appear immediately before the field declaration. It may include inline {@tags}. Its first sentence should summarize the field concisely but completely.

Constructor and method doc comments

The doc comment describing a method or constructor must appear immediately before the field declaration. Its first sentence should summarize the method or constructor concisely but completely, and should begin with a verb and complete 'This constructor …' or 'This method …', respectively. Examples are 'Initializes a newly created String object so that it represents an empty character sequence' or 'Returns the character at the specified index,' respectively. The doc comment may include inline {@tags}, and should end with

Inheritance of doc comments

The doc comments of a class or interface may be inherited by a class that extends or implements it, respectively.

If the subclass does not provide its own implementation of a method, the generated description of it lists the inherited methods with links to their descriptions.

If the subclass implements a method of its superclass or interface, but the java file does not contain a doc comment for it, the doc comment of the superclass or interface is inherited and appears word-for-word in the description of the subclass.

Example doc comments

For the String class

/**
  The String class represents character strings.
  All string literals in Java programs, such as <code>'abc'</code>,
  are implemented as instances of this class.
  <p>
  Strings are constant;
  their values cannot be changed after they are created.
  String buffers support mutable strings.
  Because String objects are immutable they can be shared.
  For example:
  <pre>

           String str = 'abc';

  </pre>
  <p>
  is equivalent to:
  <pre>

           char data[] = {'a', 'b', 'c'};
           String str = new String(data);

  </pre>

  <p>
  The class
  <code>String</code>
  includes methods for examining individual characters
  of the sequence, for comparing strings, for searching strings,
  for extracting substrings, and for creating a copy of a string
  with all characters translated to uppercase or to lowercase.
  Case mapping is based on the Unicode Standard version specified by
  the {@link Character} class.

  <p>
  Unless otherwise noted,
  passing a null argument to a constructor or method in this class
  will cause a {@link NullPointerException} to be thrown.

  @see Object.toString()
  @see StringBuffer
  @see StringBuilder
  @see Charset
  @see Serialized Form
*/
public class String { …

For the CASE_INSENSITIVE_ORDER field

/**
A Comparator that orders <code>String</code> objects as by
<code>compareToIgnoreCase</code>. This comparator is serializable.
<p>
Note that this Comparator does <i>not</i> take locale into account,
and will result in an unsatisfactory ordering for certain locales.
The java.text package provides <i>Collators</i> to allow
locale-sensitive ordering.
@see Collator.compare(String, String)
*/
public static final Comparator<String> CASE_INSENSITIVE_ORDER;

For the String(String) constructor

/**
  Initializes a newly created <code>String</code> object
  so that it represents the same sequence of characters as the argument;
  in other words, the newly created string is a copy of the argument string.
  Unless an explicit copy of <code>original</code> is needed,
  use of this constructor is unnecessary since Strings are immutable.
  @param original  a String.
*/
public String(String original) { …

For the charAt(int) method

/**
  Returns the <code>char</code> value at the specified index.
  An index ranges from <code>0</code> to <code>length()
    - 1</code>.
  The first char value of the sequence is at index <code>0</code>,
  the next at index <code>1</code>, and so on, as for array indexing.
  @param index  the index of the char value.
  @return the char value at the specified <code>index</code>
    of this string.
    The first <code>char</code> value is at index
    <code>0</code>.
  @throws IndexOutOfBoundsException  if the index argument is negative
    or not less than the length of this string.
*/
public char charAt(int index) { …

@Tags

A block tag has the form @tag followed by text. Block tags can only appear after the main description of a doc comment.

An inline tag has the form {@tag …}. Inline tags may appear anywhere in a doc comment.

The most useful javadoc tags are:

@author name
This tag adds an 'Author' entry at the end of an overview, package, or class description. Note that author entries are only generated if the -author option is given.
These inline tags produce a link to the documentation for a package, class, interface, constructor, method, or field. Depending on context, parts of package.Class#member may be omitted:
In same package and class
{@link #field}
{@link #method}
{@link #method(Type,Type,…)}
In same package, different class
{@link Class#field}
{@link Class#method}
{@link Class#method(Type,Type,…)}
{@link Class}
In another package, or from
package.html or overview
{@link package.Class#field}
{@link package.Class#method}
{@link package.Class#method(Type,…)}
{@link package.Class}
{@link package}

If a label is given, it is used as the label for the link. If no label is given, the appropriately-qualified name of the item being linked to is used as the label for the link.

{@link …} displays the link text in code font, while {@linkplain …} displays it in plain font. Otherwise they behave the same.

@param parameter-name description
This tag introduces a constructor or method parameter description. The first word after the tag is the name of the parameter, and the rest of the text following the tag is a description of the parameter.
@return description
This tag introduces a description of the value returned by a non-void method.
@see reference
This tag adds a 'See Also' entry.
@see 'string' Adds an entry with the string
@see <a href='URL#label'>label</a> Adds an entry with that link.
@see package.Class#member label Adds an entry with a link to the specified documentation. See {@link} for the possibilities.
@serial exclude
Javadoc documentation normally includes a serialized form page and links to it from many locations. This tag in the package.html file prevents this for all classes in the package.
@throws exception-classname when-description
This tag describes an exception thrown by a constructor or method. The first word is the name of the exception class that is thrown, and the remainder of the text following the tag explains the circumstances under which this exception is thrown.

See Sun's javadoc documentation for more tags.

The javadoc command

The javadoc command line synopsis is

javadoc [options] [packages] [sourcefiles] [@files]

Examples in this section are adapted from Sun's examples.

javadoc -options and arguments

The following options are particularly useful. See Sun's javadoc documentation for more.

-help
Displays help for the javadoc command.
-author
Includes the author entries in the generated documentation (by default they are not included).
-d directory
Puts the documentation tree in the named directory.
-doctitle
Gives a heading to begin the overview.
-exclude packagelist
If packages have been specified recursively with -sourcepath, then those packages in packagelist are excluded.
Creates links to existing javadoc documentation wherever appropriate. For example, if external-doc-URL points to the Java API, then parameters of type String would be linked to the documentation for java.util.String in the API. More than one -link external-doc-URL option may be given.
-overview overview-file-pathname
Read the overview from the file overview-file-pathname.
-package, -private, -protected, -public
Option Which classes, etc., are documented
-public public
-protected public protected
-package public protected (package)
-private public protected (package) private
-sourcepath pathlist
Specifies the directories in which to look for packages, classes, and source files to document. If the pathlist contains two or more directories, they are separated by colons (:). If this option is not given, the current directory is assumed.
-stylesheet pathname
Specifies an alternate stylesheet that the generated documentation will use. Otherwise, javadoc creates a file stylesheet.css in the documenation directory.
-subpackages packagelist
Equivalent to listing the packages in packagelist and all their subpackages. packagelist is colon-separated.
-use
Each class and package will be given a 'Use' page listing where that class or package is used.
-windowtitle
Specifies the window title that a browser will show for the generated documentation.

Packages

To generate documentation for a package, list the package names. If the package name is two or more levels deep, the directory names are separated by dot (.) as always in Java. javadoc will look for each package's source files in the package directory, and will look for the package directory on the -sourcepath path, or in the current directory if -sourcepath is not given.

Examples:

Source files

To generate documentation for specific source files, list the source file names (using slashes rather than dots to separate directories, and including the .java suffix).

You can include both package names and source file names on the same command line.

Examples:

@files

An @file ('at-file') is a file containing javadoc command line options and arguments. To run javadoc using options and arguments in two files whose pathname from the current directory are optsFile1 and package/OptsFile2, put @optsFile1 @package/OptsFile on the javadoc command line.

flip bgunflip