Javadoc thomasalspaugh.org/pub/fnd/javadoc.html

Introduction

Javadoc organization

Overview and package summaries

Overview documentation: the overview file

Package documentation: the `package.html` file

Doc comments

Class and interface doc comments

Constructor and method doc comments

@Tags

The `javadoc` command

`javadoc` -options and arguments

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

at the top level, as a group of several packages (with an overview summary),
within a group, as individual packages (each with a package summary),
within a package, as classes and interfaces (each with a class or interface doc comment), and
within a class or interface, as fields (each with a field doc comment), and constructors and methods (each with a constructor or method doc comment).

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:

@see block tags
@author block tags

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:

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

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:

@see block tags
@author block tags

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

a @param block tag for each of the method or constructor's parameters,
a @return block tag, if it is a method whose type is not void, and
a @throws block tag for each exception the method or constructor can throw (whether or not the method or constructor declares this).

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.

{@link package.class#member label} {@linkplain package.class#member label}

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.

-link external-doc-URL

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:

javadoc -d /home/html -sourcepath /home/src java.awt java.awt.event
javadoc -d /home/html java.awt java.awt.event

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:

javadoc -d /home/html Button.java Canvas.java Graphics*.java
javadoc -d /home/html java/awt/Button.java java/applet/Applet.java
javadoc -d /home/html /home/src/java/awt/Button.java /home/src/java/awt/Graphics*.java
javadoc -d /home/html -sourcepath /home/src java.awt /home/src/java/applet/Applet.java

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

Table of contents

Introduction

Javadoc organization

Overview and package summaries

Overview documentation: the overview file

Package documentation: the package.html file

Doc comments

Syntactic form

The essential first sentence

Class and interface doc comments

Field doc comments

Constructor and method doc comments

Inheritance of doc comments

Example doc comments

For the String class

For the CASE_INSENSITIVE_ORDER field

For the String(String) constructor

For the charAt(int) method

@Tags

The javadoc command

javadoc -options and arguments

Packages

Source files

@files

Package documentation: the `package.html` file

For the `String` class

For the `CASE_INSENSITIVE_ORDER` field

For the `String(String)` constructor

For the `charAt(int)` method

The `javadoc` command

`javadoc` -options and arguments