'\" t .\" @(#)javadoc.1 1.5 98/04/20 SMI; .\" Copyright (c) 1996 Sun Microsystems, Inc. .\" All Rights Reserved. .TH javadoc 1 "8 June 1997" .SH NAME javadoc \- Java API Documentation Generator .\" .\" This document was created by saving an HTML file as text .\" from the JavaSoft web site: .\" .\" http://www.javasoft.com:80/products/jdk/1.1/docs/tooldocs/solaris/index.html .\" .\" and adding appropriate troff macros. Because the JavaSoft web site .\" man pages can change without notice, it may be helpful to diff .\" files to identify changes other than new functionality. .\" .SH SYNOPSIS .B javadoc [ .B \-author ] [ .BI \-classpath " path" ] [ .BI \-d " directory" ] .if n .ti +5n [ .B \-d ] [ .BI \-docencoding " name" ] .if t .ti +5n [ .BI \-encoding " name" ] .if n .ti +5n [ .BI \-J " flag" ] [ .B \-nodeprecated ] [ .B \-noindex ] [ .B \-notree ] .ti +5n [ .B \-package ] [ .B \-private ] [ .B \-protected ] [ .B \-public ] .if n .ti +5n [ .BI \-sourcepath " path" ] .if t .ti +5n [ .B \-verbose ] [ .B \-version ] .if n .ti +5n [ .I package | \f2source\fP\f3.java\fP ]* .SH DESCRIPTION .IX "Documentation Generator" "" "Documentation Generator \(em \fLjavadoc\fP" .IX "Java API Documentation Generator" "" "Java API Documentation Generator \(em \fLjavadoc\fP" .IX "javadoc" "" "\fLjavadoc\fP \(em Java API Documentation Generator" The .B javadoc command parses the declarations and documentation comments in a set of Java\(tm source files and produces a set of HTML pages describing, by default, the public and protected classes, interfaces, constructors, methods, and fields. As an argument to .B javadoc you pass either a series of Java package names or source files. .LP .B javadoc generates one .B .html file for each .B .java file and each package it encounters. In addition, it produces a class hierarchy (\f3tree.html\fP) and an index of those members (\f3AllNames.html\fP). .LP When .B javadoc parses the class and member delarations, it picks up their signatures for inclusion. Further documentation can be added by including doc comments in the source code. .SS Commenting the Source Code You can include documentation comments in the source code. A doc comment consists of the characters between the /** that begins the comment and the */ that ends it. The text is divided into one or more lines. When .B javadoc parses a doc comment, leading * characters on each line are discarded; for lines other than the first, blanks and tabs preceding the initial * characters are also discarded. These comments may include HTML tags. Here is a doc comment: .RS .\" .sp 1n \f3 .nf /** * This is a doc comment. */ .fi \f1 .\" .sp 1n .RE The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the declared entity. This sentence ends at the first period that is followed by a blank, tab, or line terminator, or at the first tag (as defined below). .B javadoc copies this first sentence to the member summary at the top of the .B .html file. .LP Documentation comments are only recognized when placed immediately before class, interface, constructor, method, or field declarations. .LP When you embed HTML tags within a doc comment, you should not use heading tags such as

and

because .B javadoc creates an entire structured document and these structural tags interfere with the formatting of the generated document. .LP For the specification on documentation comments, see Chapter 18, "Documentation Comments," in .IR "The Java Language Specification" , by James Gosling, Bill Joy, and Guy Steele. (See .B SEE ALSO section below.) .SS Tagged Paragraphs .B javadoc parses special tags that are recognized when they are embedded within a Java doc comment. These doc tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with an "at" sign ( @ ). .LP Tags must start at the beginning of a line. Keep tags with the same name together within a doc comment. For example, put all .B @author tags together so that .B javadoc can tell where the list ends. .LP The tags fall into three categories: class and interface tags, field tags, and constructor and method tags; each is itemized in the following sections. .SS Class and Interface Documentation Tags .TP 15 .BI @author " name-text" Creates an "Author" entry. The text has no special internal structure. A doc comment may contain multiple .B @author tags. .TP 15 .BI @deprecated " deprecated-text" Adds a deprecated comment indicating that this API should no longer be used (even though it may continue to work). The convention is to describe the API that serves as a replacement. For example: .LP .RS 20 .B @deprecated Replaced by setBounds(int, int, int, int). .RE .LP .RS 15 If the member is obsolete and there is no replacement, the argument to .B @deprecated should be "No replacement". .RE .LP .RS 15 For more about this tag, see Deprecation of APIs. .RE .LP .TP 15 .BI @version " version-text" Adds a "Version" entry. The text has no special internal structure. A doc comment may contain, at most, one .B @version tag. Version normally refers to the version of the software (such as the JDK) that contains this feature. .TP 15 .BI @since " since-text" Adds a "Since" entry. The text has no special internal structure. This tag means that this change or feature has existed since the release number of the software specified by the .I since-text (such as the JDK). .TP 15 .BI @see " classname" Adds a hyperlinked "See Also" entry to the class. Some examples are: .RS 20 \f3 .nf @see java.lang.String @see String @see String#equals @see java.lang.Object#wait(int) @see Character#MAX_RADIX @see Java Spec .fi \f1 .RE .RS 15 The character # separates the name of a class from the name of one of its fields, methods, or constructors. One of several overloaded methods or constructors may be selected by including a parenthesized list of argument types after the method or constructor name. White space in @see's classname is significant. If there is more than one argument, there must be a single blank character between the arguments. For example: .RE .RS 20 .sp 1n .B @see java.io.File#File(java.io.File, java.lang.String) .sp 1n .RE .RS 15 A doc comment may contain more than one @see tag. .br .ne 18 .LP An example of a class comment: .RE .RS 20 \f3 .nf /** * A class representing a window on the screen. * For example: * 
*    Window win = new Window(parent);
*    win.show();
*
* * @author Sami Shaio * @version 1.5, 04/20/98 * @see java.awt.BaseWindow * @see java.awt.Button */ class Window extends BaseWindow { .\|.\|. } .fi \f1 .RE .SS Field Documentation Tags A field comments can contain only the .BR @see , .B @since and .B @deprecated tag (as described above). .LP An example of a field comment: .RS \f3 .nf /** * The X-coordinate of the window. * * @see window#1 */ int x = 1263732; .fi \f1 .RE .SS Constructor and Method Documentation Tags Can contain .B @see tags, as well as: .TP 15 \f3@param \fP\f2parameter-name description\fP Adds a parameter to the "Parameters" section. The description may be continued on the next line. .TP 15 .BI @return " description" Adds a "Returns" section, which contains the description of the return value. .TP 15 \f3@exception \fP\f2fully-qualified-class-name description\fP Adds a "Throws" section, which contains the name of the exception that may be thrown by the method. The exception is linked to its class documentation. .br .ne 19 .TP 15 .BI @see " classname" Adds a hyperlinked "See Also" entry to the method. This tag is described above. .TP 15 .BI @since " deprecated-text" See the description above. .TP 15 .BI @since " since-text" See the description above. .RS 15 .LP An example of a method doc comment: .RE .RS 20 \f3 .nf /** * Returns the character at the specified index. An index * ranges from 0 to length() - 1. * * @param index the index of the desired character. * @return the desired character. * @exception StringIndexOutOfRangeException * if the index is not in the range 0 * to length()-1. * @see java.lang.Character#charValue() */ public char charAt(int index) { .\|.\|. } .fi \f1 .RE .SH OPTIONS The following options are supported: .TP 15 .B \-author Includes .B @author tags, which are omitted by default. .TP 15 .BI \-classpath " path" NOTE: In general, do not use .BR -classpath , because it is normally not needed; use .BR -sourcepath instead to specify .B .java files. Specifies the directories from which .B javadoc is to load the .B .class files used to execute the .B javadoc tool. If .B -sourcepath is not specified, this also specifies the path .B javadoc uses to look up the .B .java files to document. It overrides the default or the \s-1\f3CLASSPATH\f2\s0 environment variable, if it is set. The path can contain multiple paths by separating them with a colon. Set the path the same way you do for the CLASSPATH environment variable. For example, the following sets two paths: current directory (.) and .BR /home/opus/myclasses : .LP .RS 20 .B javadoc -classpath .:/home/opus/myclasses myPackage.MyClass .RE .LP .RS 15 The .B -classpath option is not necessary if you call .B javadoc wrapper script directly. Normally, if you specify .B classpath it must precede .B sourcepath. However, the order of these two options does not matter if you are using the wrapper script. .RE .LP .RS 15 The value of .B classpath defaults to the current directory plus the classes location, as described in the \s0\f3CLASSPATH\s0\f2 environment variable. .RE .br .ne 7 .TP 15 .BI \-d " directory" Specifies the destination directory where .B javadoc stores the generated HTML files. (The "d" means "destination.") The directory can be absolute or relative to the current working directory. For example, the following generates the documentation for the .B java.lang package (using .SB CLASSPATH to find it) and stores the results in the directory specified by the .B \-d option: .RS 20 .sp 1n .B example% javadoc -d /home/opus/public_html/doc java.lang .RE .TP 15 .BI \-docencoding " name" Specifies output HTML file encoding name. .TP 15 .BI \-encoding " name" Specifies the source file encoding name, such as EUCJIS/SJIS. If this option is not specified, the platform default converter is used. .TP 15 .BI \-J " flag" Passes .I flag directly to the runtime system. For example, if you need to ensure that the system sets aside 32 megabytes of memory to hold the generated documentation, then use .B \-J as follows: .RS 20 .sp 1n .B example% javadoc -J-mx32m -J-ms32m .\|.\|. .RE .TP 15 .B \-nodeprecated Excludes paragraphs with the .B @deprecated tag. .RS 15 .LP Please note that the .B \-doctype option is no longer available. Only HTML documentation can be produced. .RE .TP 15 .B \-noindex Omits the default package index. .TP 15 .B \-notree Omits the default class and interface hierarchy. .TP 15 .B \-package Shows only package, protected, and public classes and members. .TP 15 .B \-private Shows all classes and members. .TP 15 .B \-protected Shows only protected and public classes and members. This is the default. .TP 15 .B \-public Shows only public classes and members. .TP 15 .BI \-sourcepath " path" Specifies the search path for source files. Does not affect the loading of class files. The .I path you specify depends on whether you specify packages or classes as .B javadoc command arguments. .RS 15 .LP When generating documentation for packages, specify the source path as the directory in the source tree that contains the topmost parent package of the those you are documenting. The default for the source path is the current .B \-classpath directory. For example, suppose you want to document a package called .B java.lang whose source files are located at: .RE .RS 20 .sp 1n .B /myapp/src/share/java/lang/*.java .RE .RS 15 .br .ne 3 .LP Because .BR java (1) is the top-most parent package, you specify that the directory that contains .B java as the source path. .RE .RS 20 .sp 1n .B example% javadoc -sourcepath /myapp/src/share .RE .RS 15 .LP When generating documentation for discrete classes, specify the source path as the directory in the source tree that contains the classes you are documenting. Note that this is different from the source path you used when documenting packages. For example, suppose you want to document a class named .B java.lang.String whose source file is located at: .RE .RS 20 .sp 1n .B /myapp/src/share/java/lang/String.java .RE .RS 15 .LP Specify the directory containing the class .B String.java as the source path. .RE .RS 20 .sp 1n .B example% javadoc \-sourcepath /myapp/src/share/java/lang .RE .RS 15 .LP You can omit the .B \-sourcepath option if you first switch to the directory you would have specified. .RE .TP 15 .B \-verbose Causes the printing of additional messages specifying the number of milliseconds taken to parse each source file. Without the verbose option, messages appear for loading the source files, generating the documentation (one message per source file), and sorting. .TP 15 .B \-version Includes .B @version tags, which are omitted by default. .SH EXAMPLES Each package name has a corresponding directory name. In the following examples, the source files are located at .BR /home/ws/src/java/awt/*java . The destination directory is .BR /home/ws/html . .SS One or More Packages To document a package, the source files (\f2\f3*.java\f1) for that package must be located in a directory having the same name as the package. If a package name is made up of several identifiers (separated by dots), each identifier represents a different directory. Thus, all .B java.awt classes must reside in a directory named .BR java/awt/ . .LP First, change to the parent directory of the topmost package (or supply the sourcepath option with that directory). Then run .BR javadoc , supplying one or more fully-specified package names. For example, if you want to document the source files in the .B java.awt package located at .B /home/ws/src/java/awt/*.java and its subpackage .BR java.awt.event : .RS .sp 1n .B example% cd /home/ws/src/ .br .B example% javadoc -d /home/ws/html java.awt java.awt.event .sp 1n .RE This generates HTML-formatted documentation for the public classes in packages .B java.awt and .B java.awt.event and puts them in the specified destination directory (\f3/home/ws/html\fP). .SS One or More Classes Change to the directory containing the class (or supply the sourcepath option with that directory). Then run .BR javadoc , supplying one or more class names. .RS \f3 .nf .sp 1n .B example% cd /home/ws/src/java/awt .B example% javadoc -d /home/ws/html Button.java Canvas.java .sp 1n .fi \f2 .RE This generates HTML-formatted documentation for the two classes and puts them in the specified destination directory (\f3/home/ws/html\fP). .SH ENVIRONMENT VARIABLES .TP 15 .SB CLASSPATH Used to provide the system with a path to user-defined classes. Directories are separated by colons, for example, .RS 20 .sp 1n .B .:/home/avh/classes:/usr/local/java/classes .RE .SH FILES .TP 20 .B AllNames.html An index of members. .TP 20 .B tree.html A hierarchy of classes. .SH ATTRIBUTES See .BR attributes (5) for a description of the following attributes: .sp .TS box; cbp-1 | cbp-1 l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE = Availability SUNWjvdev .TE .SH SEE ALSO .BR java (1), .BR javac (1), .BR javadoc (1), .BR javap (1), .BR jdb (1), .BR jre (1), .BR attributes (5) .LP .TP 10 .I The Java Language Specification http://java.sun.com/docs/books/jls/index.html .LP .TP 10 For information on related topics, use the search link @ http://java.sun.com/