diff -r 8cd632761233 -r 3d979da7bdf0 jdk/src/solaris/doc/sun/man/man1/javadoc.1 --- a/jdk/src/solaris/doc/sun/man/man1/javadoc.1 Thu Nov 21 09:23:03 2013 -0800 +++ b/jdk/src/solaris/doc/sun/man/man1/javadoc.1 Mon Nov 25 20:19:02 2013 -0800 @@ -1,4234 +1,2997 @@ -." Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved. -." DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. -." -." This code is free software; you can redistribute it and/or modify it -." under the terms of the GNU General Public License version 2 only, as -." published by the Free Software Foundation. -." -." This code is distributed in the hope that it will be useful, but WITHOUT -." ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -." FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License -." version 2 for more details (a copy is included in the LICENSE file that -." accompanied this code). -." -." You should have received a copy of the GNU General Public License version -." 2 along with this work; if not, write to the Free Software Foundation, -." Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. -." -." Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA -." or visit www.oracle.com if you need additional information or have any -." questions. -." -.TH javadoc 1 "10 May 2011" -.SH "Name" -javadoc \- The Java API Documentation Generator -.LP -Generates HTML pages of API documentation from Java source files. This document contains Javadoc examples for Solaris. -.SH "SYNOPSIS" -.LP -\f4javadoc\fP\f2\ [\ \fP\f2options\fP\f2\ ]\ [\ packagenames\ ]\ [\ sourcefilenames\ ]\ [\ \-subpackages\fP\ \f2pkg1:pkg2:...\fP\f2\ ]\ [\ \fP\f2@argfiles\fP\f2\ ]\fP -.LP -Arguments can be in any order. See processing of Source Files for details on how the Javadoc tool determines which "\f2.java\fP" files to process. -.RS 3 -.TP 3 -options -Command\-line options, as specified in this document. To see a typical use of javadoc options, see Real\-World Example. -.TP 3 -packagenames -A series of names of packages, separated by spaces, such as \f2java.lang\ java.lang.reflect\ java.awt\fP. You must separately specify each package you want to document. Wildcards are not allowed; use \-subpackages for recursion. The Javadoc tool uses \f2\-sourcepath\fP to look for these package names. See Example \- Documenting One or More Packages -.TP 3 -sourcefilenames -A series of 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 (see the Java Language Specification). Therefore, you can name files with dashes (such as \f2X\-Buffer\fP), or other illegal characters, to prevent them from being documented. This is useful for test files and template files The path that precedes the source file name determines where javadoc will look for the file. (The Javadoc tool does \f2not\fP use \f2\-sourcepath\fP to look for these source file names.) Relative paths are relative to the current directory, so passing in \f2Button.java\fP is identical to \f2./Button.java\fP. A source file name with an absolute path and a wildcard, for example, is \f2/home/src/java/awt/Graphics*.java\fP. See Example\ \-\ Documenting One or More Classes. You can also mix packagenames and sourcefilenames, as in Example\ \-\ Documenting Both Packages and Classes -.TP 3 -\-subpackages pkg1:pkg2:... -Generates documentation from source files in the specified packages and recursively in their subpackages. An alternative to supplying packagenames or sourcefilenames. -.TP 3 -@argfiles -One or more files that contain a list of Javadoc options, packagenames and sourcefilenames in any order. Wildcards (*) and \f2\-J\fP options are not allowed in these files. -.RE -.SH "DESCRIPTION" -.LP -The \f3Javadoc\fP tool parses the declarations and documentation comments in a set of Java source files and produces 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. You can use it to generate the API (Application Programming Interface) documentation or the implementation documentation for a set of source files. -.LP -You can run the Javadoc tool on entire packages, individual source files, or both. When documenting entire packages, you can either use \f2\-subpackages\fP for traversing recursively down from a top\-level directory, or pass in an explicit list of package names. When documenting individual source files, you pass in a list of source (\f2.java\fP) filenames. Examples are given at the end of this document. How Javadoc processes source files is covered next. -.SS -Processing of source files -.LP -The Javadoc tool processes files that end in "\f2.java\fP" plus other files described under Source Files. If you run the Javadoc tool by explicitly passing in individual source filenames, you can determine exactly which "\f2.java\fP" files are processed. However, that is not how most developers want to work, as it is simpler to pass in package names. The Javadoc tool can be run three ways without explicitly specifying the source filenames. You can (1) pass in package names, (2) use \f2\-subpackages\fP, and (3) use wildcards with source filenames (\f2*.java\fP). In these cases, the Javadoc tool processes a "\f2.java\fP" file only if it fulfills all of the following requirements: -.RS 3 -.TP 2 -o -Its name, after stripping off the "\f2.java\fP" suffix, is actually a legal class name (see the Java Language Specification for legal characters) -.TP 2 -o -Its directory path relative to the root of the source tree is actually a legal package name (after converting its separators to dots) -.TP 2 -o -Its package statement contains the legal package name (specified in the previous bullet) -.RE -.LP -\f3Processing of links\fP \- During a run, the Javadoc tool automatically adds cross\-reference links to package, class and member names that are being documented as part of that run. Links appear in several places: -.RS 3 -.TP 2 -o -Declarations (return types, argument types, field types) -.TP 2 -o -"See Also" sections generated from \f2@see\fP tags -.TP 2 -o -In\-line text generated from \f2{@link}\fP tags -.TP 2 -o -Exception names generated from \f2@throws\fP tags -.TP 2 -o -"Specified by" links to members in interfaces and "Overrides" links to members in classes -.TP 2 -o -Summary tables listing packages, classes and members -.TP 2 -o -Package and class inheritance trees -.TP 2 -o -The index -.RE -.LP -You can add hyperlinks to existing text for classes not included on the command line (but generated separately) by way of the \f2\-link\fP and \f2\-linkoffline\fP options. -.LP -\f3Other processing details\fP \- The Javadoc tool produces one complete document each time it is run; it cannot do incremental builds \-\- that is, it cannot modify or \f2directly\fP incorporate results from previous runs of the Javadoc tool. However, it can link to results from other runs, as just mentioned. -.LP -As implemented, the Javadoc tool requires and relies on the java compiler to do its job. The Javadoc tool calls part of \f2javac\fP to compile the declarations, ignoring the member implementation. It builds a rich internal representation of the classes, including the class hierarchy, and "use" relationships, then generates the HTML from that. The Javadoc tool also picks up user\-supplied documentation from documentation comments in the source code. -.LP -In fact, the Javadoc tool will run on \f2.java\fP source files that are pure stub files with no method bodies. This means you can write documentation comments and run the Javadoc tool in the earliest stages of design while creating the API, before writing the implementation. -.LP -Relying on the compiler ensures that the HTML output corresponds exactly with the actual implementation, which may rely on implicit, rather than explicit, source code. For example, the Javadoc tool documents default constructors (see Java Language Specification) that are present in the \f2.class\fP files but not in the source code. -.LP -In many cases, the Javadoc tool allows you to generate documentation for source files whose code is incomplete or erroneous. This is a benefit that enables you to generate documentation before all debugging and troubleshooting is done. For example, according to the \f2Java Language Specification\fP, a class that contains an abstract method should itself be declared abstract. The Javadoc tool does not check for this, and would proceed without a warning, whereas the javac compiler stops on this error. The Javadoc tool does do some primitive checking of doc comments. Use the DocCheck doclet to check the doc comments more thoroughly. -.LP -When the Javadoc tool builds its internal structure for the documentation, it loads all referenced classes. Because of this, the Javadoc tool must be able to find all referenced classes, whether bootstrap classes, extensions, or user classes. For more about this, see -.na -\f2How Classes Are Found\fP @ -.fi -http://download.oracle.com/javase/7/docs/technotes/tools/findingclasses.html. Generally speaking, classes you create must either be loaded as an extension or in the Javadoc tool's class path. -.SS -Javadoc Doclets -.LP -You can customize the content and format of the Javadoc tool's output by using doclets. The Javadoc tool has a default "built\-in" doclet, called the standard doclet, that generates HTML\-formatted API documentation. You can modify or subclass the standard doclet, or write your own doclet to generate HTML, XML, MIF, RTF or whatever output format you'd like. Information about doclets and their use is at the following locations: -.RS 3 -.TP 2 -o -.na -\f2Javadoc Doclets\fP @ -.fi -http://download.oracle.com/javase/7/docs/technotes/guides/javadoc/index.html -.TP 2 -o -The \f2\-doclet\fP command\-line option -.RE -.LP -When a custom doclet is not specified with the \f2\-doclet\fP command line option, the Javadoc tool will use the default standard doclet. The javadoc tool has several command line options that are available regardless of which doclet is being used. The standard doclet adds a supplementary set of command line options. Both sets of options are described below in the options section. -.SS -Related Documentation and Doclets -.RS 3 -.TP 2 -o -.na -\f2Javadoc Enhancements\fP @ -.fi -http://download.oracle.com/javase/7/docs/technotes/guides/javadoc/index.html for details about improvements added in Javadoc. -.TP 2 -o -.na -\f2Javadoc FAQ\fP @ -.fi -http://java.sun.com/j2se/javadoc/faq/index.html for answers to common questions, information about Javadoc\-related tools, and workarounds for bugs. -.TP 2 -o -.na -\f2How to Write Doc Comments for Javadoc\fP @ -.fi -http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html for more information about Sun conventions for writing documentation comments. -.TP 2 -o -.na -\f2Requirements for Writing API Specifications\fP @ -.fi -http://java.sun.com/j2se/javadoc/writingapispecs/index.html \- Standard requirements used when writing the Java SE Platform Specification. It can be useful whether you are writing API specifications in source file documentation comments or in other formats. It covers requirements for packages, classes, interfaces, fields and methods to satisfy testable assertions. -.TP 2 -o -.na -\f2Documentation Comment Specification\fP @ -.fi -http://java.sun.com/docs/books/jls/first_edition/html/18.doc.html \- The original specification on documentation comments, Chapter 18, Documentation Comments, in the \f2Java Language Specification\fP, First Edition, by James Gosling, Bill Joy, and Guy Steele. (This chapter was removed from the second edition.) -.TP 2 -o -.na -\f2DocCheck Doclet\fP @ -.fi -http://www.oracle.com/technetwork/java/javase/documentation/index\-141437.html \- Checks doc comments in source files and generates a report listing the errors and irregularities it finds. It is part of the Doc Check Utilities. -.TP 2 -o -.na -\f2MIF Doclet\fP @ -.fi -http://java.sun.com/j2se/javadoc/mifdoclet/ \- Can automate the generation of API documentation in MIF, FrameMaker and PDF formats. MIF is Adobe FrameMaker's interchange format. -.RE -.SS -Terminology -.LP -The terms \f2documentation comment\fP, \f2doc comment\fP, \f2main description\fP, \f2tag\fP, \f2block tag\fP, and \f2in\-line tag\fP are described at Documentation Comments. These other terms have specific meanings within the context of the Javadoc tool: -.RS 3 -.TP 3 -generated document -The document generated by the javadoc tool from the doc comments in Java source code. The default generated document is in HTML and is created by the standard doclet. -.LP -.TP 3 -name -A name of a program element written in the Java Language \-\- that is, the name of a package, class, interface, field, constructor or method. A name can be fully\-qualified, such as \f2java.lang.String.equals(java.lang.Object)\fP, or partially\-qualified, such as \f2equals(Object)\fP. -.LP -.TP 3 -documented classes -The classes and interfaces for which detailed documentation is generated during a javadoc run. To be documented, the source files must be available, their source filenames or package names must be passed into the javadoc command, and they must not be filtered out by their access modifier (public, protected, package\-private or private). We also refer to these as the classes included in the javadoc output, or the \f2included classes\fP. -.LP -.TP 3 -included classes -Classes and interfaces whose details are documented during a run of the Javadoc tool. Same as \f2documented classes\fP. -.LP -.TP 3 -excluded classes -Classes and interfaces whose details are \f2not\fP documented during a run of the Javadoc tool. -.LP -.TP 3 -referenced classes -The classes and interfaces that are explicitly referred to in the definition (implementation) or doc comments of the documented classes and interfaces. Examples of references include return type, parameter type, cast type, extended class, implemented interface, imported classes, classes used in method bodies, @see, {@link}, {@linkplain}, and {@inheritDoc} tags. (Notice this definition has changed since -.na -\f21.3\fP @ -.fi -http://download.oracle.com/javase/1.3/docs/tooldocs/solaris/javadoc.html#referencedclasses.) When the Javadoc tool is run, it should load into memory all of the referenced classes in javadoc's bootclasspath and classpath. (The Javadoc tool prints a "Class not found" warning for referenced classes not found.) The Javadoc tool can derive enough information from the .class files to determine their existence and the fully\-qualified names of their members. -.LP -.TP 3 -external referenced classes -The referenced classes whose documentation is not being generated during a javadoc run. In other words, these classes are not passed into the Javadoc tool on the command line. Links in the generated documentation to those classes are said to be \f2external references\fP or \f2external links\fP. For example, if you run the Javadoc tool on only the \f2java.awt\fP package, then any class in \f2java.lang\fP, such as \f2Object\fP, is an external referenced class. External referenced classes can be linked to using the \f2\-link\fP and \f2\-linkoffline\fP options. An important property of an external referenced class is that its source comments are normally not available to the Javadoc run. In this case, these comments cannot be inherited. -.RE -.SH "SOURCE FILES" -.LP -The Javadoc tool will generate output originating from four different types of "source" files: Java language source files for classes (\f2.java\fP), package comment files, overview comment files, and miscellaneous unprocessed files. This section also covers test files and template files that can also be in the source tree, but which you want to be sure not to document. -.SS -Class Source Code Files -.LP -Each class or interface and its members can have their own documentation comments, contained in a \f2.java\fP file. For more details about these doc comments, see Documentation Comments. -.SS -Package Comment Files -.LP -Each package can have its own documentation comment, contained in its own "source" file, that the Javadoc tool will merge into the package summary page that it generates. You typically include in this comment any documentation that applies to the entire package. -.LP -To create a package comment file, you have a choice of two files to place your comments: -.RS 3 -.TP 2 -o -\f2package\-info.java\fP \- Can contain a package declaration, package annotations, package comments and Javadoc tags. This file is generally preferred over package.html. -.TP 2 -o -\f2package.html\fP \- Can contain only package comments and Javadoc tags, no package annotations. -.RE -.LP -A package may have a single \f2package.html\fP file or a single \f2package\-info.java\fP file but not both. Place either file in the package directory in the source tree along with your \f2.java\fP files. -.LP -\f4package\-info.java\fP \- This file can contain a package comment of the following structure \-\- the comment is placed before the package declaration: -.LP -File: \f2java/applet/package\-info.java\fP -.nf -\f3 -.fl -/** -.fl - * Provides the classes necessary to create an -.fl - * applet and the classes an applet uses -.fl - * to communicate with its applet context. -.fl - *
-.fl - * The applet framework involves two entities: -.fl - * the applet and the applet context. -.fl - * An applet is an embeddable window (see the -.fl - * {@link java.awt.Panel} class) with a few extra -.fl - * methods that the applet context can use to -.fl - * initialize, start, and stop the applet. -.fl - * -.fl - * @since 1.0 -.fl - * @see java.awt -.fl - */ -.fl -package java.lang.applet; -.fl -\fP -.fi -.LP -Note that while the comment separators \f2/**\fP and \f2/*\fP must be present, the leading asterisks on the intermediate lines can be omitted. -.LP -\f4package.html\fP \- This file can contain a package comment of the following structure \-\- the comment is placed in the \f2
\fP element: -.LP -File: \f2java/applet/package.html\fP -.nf -\f3 -.fl - -.fl - -.fl -Provides the classes necessary to create an applet and the -.fl -classes an applet uses to communicate with its applet context. -.fl --.fl -The applet framework involves two entities: the applet -.fl -and the applet context. An applet is an embeddable -.fl -window (see the {@link java.awt.Panel} class) with a -.fl -few extra methods that the applet context can use to -.fl -initialize, start, and stop the applet. -.fl +'\" t +.\" Copyright (c) 1994, 2013, Oracle and/or its affiliates. All rights reserved. +.\" +.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. +.\" +.\" This code is free software; you can redistribute it and/or modify it +.\" under the terms of the GNU General Public License version 2 only, as +.\" published by the Free Software Foundation. +.\" +.\" This code is distributed in the hope that it will be useful, but WITHOUT +.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +.\" version 2 for more details (a copy is included in the LICENSE file that +.\" accompanied this code). +.\" +.\" You should have received a copy of the GNU General Public License version +.\" 2 along with this work; if not, write to the Free Software Foundation, +.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. +.\" +.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA +.\" or visit www.oracle.com if you need additional information or have any +.\" questions. +.\" +.\" Arch: generic +.\" Software: JDK 8 +.\" Date: 10 May 2011 +.\" SectDesc: Basic Tools +.\" Title: javadoc.1 +.\" +.if n .pl 99999 +.TH javadoc 1 "10 May 2011" "JDK 8" "Basic Tools" +.\" ----------------------------------------------------------------- +.\" * Define some portability stuff +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" http://bugs.debian.org/507673 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- + +.SH NAME +javadoc \- Generates HTML pages of API documentation from Java source files\&. +.SH SYNOPSIS +.sp +.nf + +\fBjavadoc\fR {\fIpackages\fR|\fIsource\-files\fR} [\fIoptions\fR] [\fI@argfiles\fR] +.fi +.sp +.TP +\fIpackages\fR +Names of packages that you want to document, separated by spaces, for example \f3java\&.lang java\&.lang\&.reflect java\&.awt\fR\&. If you want to also document the subpackages, use the \f3-subpackages\fR option to specify the packages\&. + +By default, \f3javadoc\fR looks for the specified packages in the current directory and subdirectories\&. Use the \f3-sourcepath\fR option to specify the list of directories where to look for packages\&. +.TP +\fIsource-files\fR +Names of Java source files that you want to document, separated by spaces, for example \f3Class\&.java Object\&.java Button\&.java\fR\&. By default, \f3javadoc\fR looks for the specified classes in the current directory\&. However, you can specify the full path to the class file and use wildcard characters, for example \f3/home/src/java/awt/Graphics*\&.java\fR\&. You can also specify the path relative to the current directory\&. +.TP +\fIoptions\fR +Command-line options, separated by spaces\&. See Options\&. +.TP +\fI@argfiles\fR +Names of files that contain a list of \f3javadoc\fR command options, package names and source file names in any order\&. +.SH DESCRIPTION +The \f3javadoc\fR command parses the declarations and documentation comments in a set of Java source files and produces a corresponding set of HTML pages that describe (by default) the public and protected classes, nested classes (but not anonymous inner classes), interfaces, constructors, methods, and fields\&. You can use the \f3javadoc\fR command to generate the API documentation or the implementation documentation for a set of source files\&. +.PP +You can run the \f3javadoc\fR command on entire packages, individual source files, or both\&. When documenting entire packages, you can either use the \f3-subpackages\fR option to recursively traverse a directory and its subdirectories, or to pass in an explicit list of package names\&. When you document individual source files, pass in a list of Java source file names\&. See Simple Examples\&. +.SS PROCESS\ SOURCE\ FILES +The \f3javadoc\fR command processes files that end in source and other files described in Source Files\&. If you run the \f3javadoc\fR command by passing in individual source file names, then you can determine exactly which source files are processed\&. However, that is not how most developers want to work, because it is simpler to pass in package names\&. The \f3javadoc\fR command can be run three ways without explicitly specifying the source file names\&. You can pass in package names, use the \f3-subpackages\fR option, or use wild cards with source file names\&. In these cases, the \f3javadoc\fR command processes a source file only when the file fulfills all of the following requirements: +.TP 0.2i +\(bu +The file name prefix (with \f3\&.java\fR removed) is a valid class name\&. +.TP 0.2i +\(bu +The path name relative to the root of the source tree is a valid package name after the separators are converted to dots\&. +.TP 0.2i +\(bu +The package statement contains the valid package name\&. +.PP +Processing Links + +During a run, the \f3javadoc\fR command adds cross-reference links to package, class, and member names that are being documented as part of that run\&. Links appear in the following places\&. See Javadoc Tags for a description of the @ tags\&. +.TP 0.2i +\(bu +Declarations (return types, argument types, and field types)\&. +.TP 0.2i +\(bu +\fISee Also\fR sections that are generated from \f3@see\fR tags\&. +.TP 0.2i +\(bu +Inline text generated from \f3{@link}\fR tags\&. +.TP 0.2i +\(bu +Exception names generated from \f3@throws\fR tags\&. +.TP 0.2i +\(bu +\fISpecified by\fR links to interface members and \fIOverrides\fR links to class members\&. See Method Comment Inheritance\&. +.TP 0.2i +\(bu +Summary tables listing packages, classes and members\&. +.TP 0.2i +\(bu +Package and class inheritance trees\&. +.TP 0.2i +\(bu +The index\&. +.PP +You can add links to existing text for classes not included on the command line (but generated separately) by way of the \f3-link\fR and \f3-linkoffline\fR options\&. +.PP +Processing Details + +The \f3javadoc\fR command produces one complete document every time it runs\&. It does not do incremental builds that modify or directly incorporate the results from earlier runs\&. However, the \f3javadoc\fR command can link to results from other runs\&. +.PP +The \f3javadoc\fR command implementation requires and relies on the Java compiler\&. The \f3javadoc\fR command calls part of the \f3javac\fR command to compile the declarations and ignore the member implementations\&. The \f3javadoc\fR command builds a rich internal representation of the classes that includes the class hierarchy and use relationships to generate the HTML\&. The \f3javadoc\fR command also picks up user-supplied documentation from documentation comments in the source code\&. See Documentation Comments\&. +.PP +The \f3javadoc\fR command runs on source files that are pure stub files with no method bodies\&. This means you can write documentation comments and run the \f3javadoc\fR command in the early stages of design before API implementation\&. +.PP +Relying on the compiler ensures that the HTML output corresponds exactly with the actual implementation, which may rely on implicit, rather than explicit, source code\&. For example, the \f3javadoc\fR command documents default constructors that are present in the compiled class files but not in the source code\&. +.PP +In many cases, the \f3javadoc\fR command lets you generate documentation for source files with incomplete or erroneous code\&. You can generate documentation before all debugging and troubleshooting is done\&. The \f3javadoc\fR command does primitive checking of documentation comments\&. +.PP +When the \f3javadoc\fR command builds its internal structure for the documentation, it loads all referenced classes\&. Because of this, the \f3javadoc\fR command must be able to find all referenced classes, whether bootstrap classes, extensions, or user classes\&. See How Classes Are Found at http://docs\&.oracle\&.com/javase/8/docs/technotes/tools/findingclasses\&.html +.PP +Typically, classes you create must either be loaded as an extension or in the \f3javadoc\fR command class path\&. +.SS JAVADOC\ DOCLETS +You can customize the content and format of the \f3javadoc\fR command output with doclets\&. The \f3javadoc\fR command has a default built-in doclet, called the standard doclet, that generates HTML-formatted API documentation\&. You can modify or make a subclass of the standard doclet, or write your own doclet to generate HTML, XML, MIF, RTF or whatever output format you want\&. +.PP +When a custom doclet is not specified with the \f3-doclet\fR option, the \f3javadoc\fR command uses the default standard doclet\&. The \f3javadoc\fR command has several options that are available regardless of which doclet is being used\&. The standard doclet adds a supplementary set of command-line options\&. See Options\&. +.SH SOURCE\ FILES +The \f3javadoc\fR command generates output that originates from the following types of source files: Java language source files for classes (\f3\&.java\fR), package comment files, overview comment files, and miscellaneous unprocessed files\&. This section also describes test files and template files that can also be in the source tree, but that you want to be sure not to document\&. +.SS CLASS\ SOURCE\ FILES +Each class or interface and its members can have their own documentation comments contained in a source file\&. See Documentation Comments\&. +.SS PACKAGE\ COMMENT\ FILES +Each package can have its own documentation comment, contained in its own source file, that the \f3javadoc\fR command merges into the generated package summary page\&. You typically include in this comment any documentation that applies to the entire package\&. +.PP +To create a package comment file, you can place your comments in one of the following files: +.TP 0.2i +\(bu +The \f3package-info\&.java\fR file can contain the package declaration, package annotations, package comments, and Javadoc tags\&. This file is preferred\&. +.TP 0.2i +\(bu +The \f3package\&.html\fR file contains only package comments and Javadoc tags\&. No package annotations\&. +.PP +A package can have a single \f3package\&.html\fR file or a single \f3package-info\&.java\fR file, but not both\&. Place either file in the package directory in the source tree with your source files\&. +.PP +The package-info\&.java File -.fl -@since 1.0 -.fl -@see java.awt -.fl - -.fl - -.fl -\fP -.fi -.LP -Notice this is just a normal HTML file and does not include a package declaration. The content of the package comment file is written in HTML, like all other comments, with one exception: The documentation comment should not include the comment separators \f2/**\fP and \f2*/\fP or leading asterisks. When writing the comment, you should make the first sentence a summary about the package, and not put a title or any other text between \f2
\fP and the first sentence. You can include package tags; as with any documentation comment, all block tags must appear after the main description. If you add a \f2@see\fP tag in a package comment file, it must have a fully\-qualified name. For more details, see the -.na -\f2example of \fP\f2package.html\fP @ -.fi -http://www.oracle.com/technetwork/java/javase/documentation/index\-137868.html#packagecomments. -.LP -\f3Processing of package comment file\fP \- When the Javadoc tool runs, it will automatically look for the package comment file; if found, the Javadoc tool does the following: -.RS 3 -.TP 2 -o -Copies the comment for processing. (For \f2package.html\fP, copies all content between \f2\fP and \f2\fP HTML tags. You can include a \f2\fP section to put a \f2\fP +.fi +.nf +\f3 * The applet framework involves two entities:\fP +.fi +.nf +\f3 * the applet and the applet context\&.\fP +.fi +.nf +\f3 * An applet is an embeddable window (see the\fP +.fi +.nf +\f3 * {@link java\&.awt\&.Panel} class) with a few extra\fP +.fi +.nf +\f3 * methods that the applet context can use to \fP +.fi +.nf +\f3 * initialize, start, and stop the applet\&.\fP +.fi +.nf +\f3 *\fP +.fi +.nf +\f3 * @since 1\&.0\fP +.fi +.nf +\f3 * @see java\&.awt\fP +.fi +.nf +\f3 */\fP +.fi +.nf +\f3package java\&.lang\&.applet;\fP +.fi +.nf +\f3\fR +.fi +.sp + +.PP +The package\&.html File + +The \f3package\&.html\fR file can contain a package comment of the following structure\&. The comment is placed in the \f3
\fR element\&. +.PP +File: \f3java/applet/package\&.html\fR +.sp +.nf +\f3\fP +.fi +.nf +\f3\fP +.fi +.nf +\f3Provides the classes necessary to create an applet and the \fP +.fi +.nf +\f3classes an applet uses to communicate with its applet context\&.\fP +.fi +.nf +\f3\fP +.fi +.nf +\f3The applet framework involves two entities: the applet\fP +.fi +.nf +\f3and the applet context\&. An applet is an embeddable\fP +.fi +.nf +\f3window (see the {@link java\&.awt\&.Panel} class) with a\fP +.fi +.nf +\f3few extra methods that the applet context can use to\fP +.fi +.nf +\f3initialize, start, and stop the applet\&. \fP +.fi +.nf +\f3\fR +.fi +.nf +\f3@since 1\&.0 \fP +.fi +.nf +\f3@see java\&.awt\fP +.fi +.nf +\f3\fP +.fi +.nf +\f3\fP +.fi +.nf +\f3\fR +.fi +.sp +The \f3package\&.html\fR file is a typical HTML file and does not include a package declaration\&. The content of the package comment file is written in HTML with one exception\&. The documentation comment should not include the comment separators \f3/**\fR and \f3*/\fR or leading asterisks\&. When writing the comment, make the first sentence a summary about the package, and do not put a title or any other text between the \f3
\fR tag and the first sentence\&. You can include package tags\&. All block tags must appear after the main description\&. If you add an \f3@see\fR tag in a package comment file, then it must have a fully qualified name\&. +.PP +Processing the Comment File + +When the \f3javadoc\fR command runs, it searches for the package comment file\&. If the package comment file is found, then the \f3javadoc\fR command does the following: +.TP 0.2i +\(bu +Copies the comment for processing\&. For package\&.html, the \f3javadoc\fR command copies all content between the \f3\fR and \f3\fR HTML tags\&. You can include a \f3\fR section to put a \f3\fP tag, and its indentation will be honored. Spaces are generally interpreted by browsers more uniformly than tabs. Indentation is relative to the left margin (rather than the separator \f2/**\fP or \f2\fP tag). -.LP -\f3First sentence\fP \- 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 block tag. The Javadoc tool copies this first sentence to the member summary at the top of the HTML page. -.LP -\f3Declaration with multiple fields\fP \- Java allows declaring multiple fields in a single statement, but this statement can have only one documentation comment, which is copied for all fields. Therefore if you want individual documentation comments for each field, you must declare each field in a separate statement. For example, the following documentation comment doesn't make sense written as a single declaration and would be better handled as two declarations: -.nf -\f3 -.fl -/** -.fl - * The horizontal and vertical distances of point (x,y) -.fl - */ -.fl -public int x, y; // Avoid this -.fl -\fP -.fi -.LP -The Javadoc tool generates the following documentation from the above code: -.nf -\f3 -.fl -public int \fP\f3x\fP -.fl -.fi -.RS 3 -The horizontal and vertical distances of point (x,y) -.RE -.nf -\f3 -.fl -public int \fP\f3y\fP -.fl -.fi -.RS 3 -The horizontal and vertical distances of point (x,y) -.RE -.LP -\f3Use header tags carefully\fP \- When writing documentation comments for members, it's best not to use HTML heading tags such asand
, because the Javadoc tool creates an entire structured document and these structural tags might interfere with the formatting of the generated document. However, it is fine to use these headings in class and package comments to provide your own structure. -.SS -Automatic Copying of Method Comments -.LP -The Javadoc tool has the ability to copy or "inherit" method comments in classes and interfaces under the following two circumstances. Constructors, fields and nested classes do not inherit doc comments. -.RS 3 -.TP 2 -o -\f3Automatically inherit comment to fill in missing text\fP \- When a main description, or \f2@return\fP, \f2@param\fP or \f2@throws\fP tag is missing from a method comment, the Javadoc tool copies the corresponding main description or tag comment from the method it overrides or implements (if any), according to the algorithm below. -.LP -More specifically, when a \f2@param\fP tag for a particular parameter is missing, then the comment for that parameter is copied from the method further up the inheritance hierarchy. When a \f2@throws\fP tag for a particular exception is missing, the \f2@throws\fP tag is copied \f2only if that exception is declared\fP. -.LP -This behavior contrasts with version 1.3 and earlier, where the presence of any main description or tag would prevent all comments from being inherited. -.TP 2 -o -\f3Explicitly inherit comment with {@inheritDoc} tag\fP \- Insert the inline tag \f2{@inheritDoc}\fP in a method main description or \f2@return\fP, \f2@param\fP or \f2@throws\fP tag comment \-\- the corresponding inherited main description or tag comment is copied into that spot. -.RE -.LP -The source file for the inherited method need only be on the path specified by \-sourcepath for the doc comment to actually be available to copy. Neither the class nor its package needs to be passed in on the command line. This contrasts with 1.3.x and earlier releases, where the class had to be a documented class -.LP -\f3Inherit from classes and interfaces\fP \- Inheriting of comments occurs in all three possible cases of inheritance from classes and interfaces: -.RS 3 -.TP 2 -o -When a method in a class overrides a method in a superclass -.TP 2 -o -When a method in an interface overrides a method in a superinterface -.TP 2 -o -When a method in a class implements a method in an interface -.RE -.LP -In the first two cases, for method overrides, the Javadoc tool generates a subheading "Overrides" in the documentation for the overriding method, with a link to the method it is overriding, whether or not the comment is inherited. -.LP -In the third case, when a method in a given class implements a method in an interface, the Javadoc tool generates a subheading "Specified by" in the documentation for the overriding method, with a link to the method it is implementing. This happens whether or not the comment is inherited. -.LP -\f3Algorithm for Inheriting Method Comments\fP \- If a method does not have a doc comment, or has an {@inheritDoc} tag, the Javadoc tool searches for an applicable comment using the following algorithm, which is designed to find the most specific applicable doc comment, giving preference to interfaces over superclasses: -.RS 3 -.TP 3 -1. -Look in each directly implemented (or extended) interface in the order they appear following the word implements (or extends) in the method declaration. Use the first doc comment found for this method. -.TP 3 -2. -If step 1 failed to find a doc comment, recursively apply this entire algorithm to each directly implemented (or extended) interface, in the same order they were examined in step 1. -.TP 3 -3. -If step 2 failed to find a doc comment and this is a class other than Object (not an interface): -.RS 3 -.TP 3 -a. -If the superclass has a doc comment for this method, use it. -.TP 3 -b. -If step 3a failed to find a doc comment, recursively apply this entire algorithm to the superclass. -.RE -.RE -.SH "JAVADOC TAGS" -.LP -The Javadoc tool parses special tags 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 (\f2@\fP) and are case\-sensitive \-\- they must be typed with the uppercase and lowercase letters as shown. A tag must start at the beginning of a line (after any leading spaces and an optional asterisk) or it is treated as normal text. By convention, tags with the same name are grouped together. For example, put all \f2@see\fP tags together. -.LP -Tags come in two types: -.RS 3 -.TP 2 -o -\f3Block tags\fP \- Can be placed only in the tag section that follows the main description. Block tags are of the form: \f2@tag\fP. -.TP 2 -o -\f3Inline tags\fP \- Can be placed anywhere in the main description or in the comments for block tags. Inline tags are denoted by curly braces: \f2{@tag}\fP. -.RE -.LP -For information about tags we might introduce in future releases, see -.na -\f2Proposed Tags\fP @ -.fi -http://java.sun.com/j2se/javadoc/proposed\-tags.html. -.LP -The current tags are: -.LP -.TS -.if \n+(b.=1 .nr d. \n(.c-\n(c.-1 -.de 35 -.ps \n(.s -.vs \n(.vu -.in \n(.iu -.if \n(.u .fi -.if \n(.j .ad -.if \n(.j=0 .na -.. -.nf -.nr #~ 0 -.if n .nr #~ 0.6n -.ds #d .d -.if \(ts\n(.z\(ts\(ts .ds #d nl -.fc -.nr 33 \n(.s -.rm 80 81 -.nr 80 0 -.nr 38 \w\f3Tag\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2@author\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2{@code}\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2{@docRoot}\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2@deprecated\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2@exception\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2{@inheritDoc}\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2{@link}\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2{@linkplain}\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2{@literal}\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2@param\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2@return\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2@see\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2@serial\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2@serialData\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2@serialField\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2@since\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2@throws\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2{@value}\fP -.if \n(80<\n(38 .nr 80 \n(38 -.nr 38 \w\f2@version\fP -.if \n(80<\n(38 .nr 80 \n(38 -.80 -.rm 80 -.nr 81 0 -.nr 38 \w\f3Introduced in JDK/SDK\fP -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.0 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.5 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.3 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.0 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.0 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.4 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.2 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.4 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.5 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.0 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.0 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.0 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.2 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.2 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.2 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.1 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.2 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.4 -.if \n(81<\n(38 .nr 81 \n(38 -.nr 38 \w1.0 -.if \n(81<\n(38 .nr 81 \n(38 -.81 -.rm 81 -.nr 38 1n -.nr 79 0 -.nr 40 \n(79+(0*\n(38) -.nr 80 +\n(40 -.nr 41 \n(80+(3*\n(38) -.nr 81 +\n(41 -.nr TW \n(81 -.if t .if \n(TW>\n(.li .tm Table at line 873 file Input is too wide - \n(TW units -.fc -.nr #T 0-1 -.nr #a 0-1 -.eo -.de T# -.ds #d .d -.if \(ts\n(.z\(ts\(ts .ds #d nl -.mk ## -.nr ## -1v -.ls 1 -.ls -.. -.ec -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f3Tag\fP\h'|\n(41u'\f3Introduced in JDK/SDK\fP -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2@author\fP\h'|\n(41u'1.0 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2{@code}\fP\h'|\n(41u'1.5 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2{@docRoot}\fP\h'|\n(41u'1.3 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2@deprecated\fP\h'|\n(41u'1.0 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2@exception\fP\h'|\n(41u'1.0 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2{@inheritDoc}\fP\h'|\n(41u'1.4 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2{@link}\fP\h'|\n(41u'1.2 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2{@linkplain}\fP\h'|\n(41u'1.4 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2{@literal}\fP\h'|\n(41u'1.5 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2@param\fP\h'|\n(41u'1.0 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2@return\fP\h'|\n(41u'1.0 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2@see\fP\h'|\n(41u'1.0 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2@serial\fP\h'|\n(41u'1.2 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2@serialData\fP\h'|\n(41u'1.2 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2@serialField\fP\h'|\n(41u'1.2 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2@since\fP\h'|\n(41u'1.1 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2@throws\fP\h'|\n(41u'1.2 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2{@value}\fP\h'|\n(41u'1.4 -.ta \n(80u \n(81u -.nr 31 \n(.f -.nr 35 1m -\&\h'|\n(40u'\f2@version\fP\h'|\n(41u'1.0 -.fc -.nr T. 1 -.T# 1 -.35 -.TE -.if \n-(b.=0 .nr c. \n(.c-\n(d.-42 -.LP -For custom tags, see the \-tag option. -.RS 3 -.TP 3 -@author\ name\-text -Adds an "Author" entry with the specified \f2name\-text\fP to the generated docs when the \-author option is used. A doc comment may contain multiple \f2@author\fP tags. You can specify one name per \f2@author\fP tag or multiple names per tag. In the former case, the Javadoc tool inserts a comma (\f2,\fP) and space between names. In the latter case, the entire text is simply copied to the generated document without being parsed. Therefore, you can use multiple names per line if you want a localized name separator other than comma. +Documentation comments are recognized only when placed immediately before class, interface, constructor, method, or field declarations\&. Documentation comments placed in the body of a method are ignored\&. The \f3javadoc\fR command recognizes only one documentation comment per declaration statement\&. See Where Tags Can Be Used\&. +.PP +A common mistake is to put an \f3import\fR statement between the class comment and the class declaration\&. Do not put an \f3import\fR statement at this location because the \f3javadoc\fR command ignores the class comment\&. +.sp +.nf +\f3/**\fP +.fi +.nf +\f3 * This is the class comment for the class Whatever\&.\fP +.fi +.nf +\f3 */\fP +.fi +.nf +\f3\fR +.fi +.nf +\f3import com\&.example; // MISTAKE \- Important not to put import statement here\fP +.fi +.nf +\f3\fR +.fi +.nf +\f3public class Whatever{ }\fP +.fi +.nf +\f3\fR +.fi +.sp + +.PP +Parts of Comments + +A documentation comment has a main description followed by a tag section\&. The main description begins after the starting delimiter \f3/**\fR and continues until the tag section\&. The tag section starts with the first block tag, which is defined by the first \f3@\fR character that begins a line (ignoring leading asterisks, white space, and leading separator \f3/**\fR)\&. It is possible to have a comment with only a tag section and no main description\&. The main description cannot continue after the tag section begins\&. The argument to a tag can span multiple lines\&. There can be any number of tags, and some types of tags can be repeated while others cannot\&. For example, this \f3@see\fR tag starts the tag section: +.sp +.nf +\f3/**\fP +.fi +.nf +\f3 * This sentence holds the main description for this documentation comment\&.\fP +.fi +.nf +\f3 * @see java\&.lang\&.Object\fP +.fi +.nf +\f3 */\fP +.fi +.nf +\f3\fR +.fi +.sp + +.PP +Block and inline Tags + +A tag is a special keyword within a documentation comment that the \f3javadoc\fR command processes\&. There are two kinds of tags: block tags, which appear as an \f3@tag\fR tag (also known as standalone tags), and inline tags, which appear within braces, as an \f3{@tag}\fR tag\&. To be interpreted, a block tag must appear at the beginning of a line, ignoring leading asterisks, white space, and the separator (\f3/**\fR)\&. This means you can use the \f3@\fR character elsewhere in the text and it will not be interpreted as the start of a tag\&. If you want to start a line with the \f3@\fR character and not have it be interpreted, then use the HTML entity \f3@\fR\&. Each block tag has associated text, which includes any text following the tag up to, but not including, either the next tag, or the end of the documentation comment\&. This associated text can span multiple lines\&. An inline tag is allowed and interpreted anywhere that text is allowed\&. The following example contains the \f3@deprecated\fR block tag and the \f3{@link}\fR inline tag\&. See Javadoc Tags\&. +.sp +.nf +\f3/**\fP +.fi +.nf +\f3 * @deprecated As of JDK 1\&.1, replaced by {@link #setBounds(int,int,int,int)}\fP +.fi +.nf +\f3 */\fP +.fi +.nf +\f3\fR +.fi +.sp + +.PP +Write Comments in HTML + +The text must be written in HTML with HTML entities and HTML tags\&. You can use whichever version of HTML your browser supports\&. The standard doclet generates HTML 3\&.2-compliant code elsewhere (outside of the documentation comments) with the inclusion of cascading style sheets and frames\&. HTML 4\&.0 is preferred for generated files because of the frame sets\&. +.PP +For example, entities for the less than symbol (<) and the greater than symbol (>) should be written as \f3<\fR and \f3>\fR\&. Similarly, the ampersand (&) should be written as \f3&\fR\&. The bold HTML tag \f3\fR is shown in the following example\&. +.sp +.nf +\f3/**\fP +.fi +.nf +\f3 * This is a doc comment\&.\fP +.fi +.nf +\f3 * @see java\&.lang\&.Object\fP +.fi +.nf +\f3 */\fP +.fi +.nf +\f3\fR +.fi +.sp + +.PP +Leading Asterisks + +When the \f3javadoc\fR command parses a documentation comment, leading asterisks (*) on each line are discarded, and blanks and tabs that precede the initial asterisks (*) are also discarded\&. If you omit the leading asterisk on a line, then the leading white space is no longer removed so that you can paste code examples directly into a documentation comment inside a \f3
\fR tag with its indentation preserved\&. Spaces are interpreted by browsers more uniformly than tabs\&. Indentation is relative to the left margin (rather than the separator \f3/**\fR or \f3\fR tag)\&. +.PP +First Sentence + +The first sentence of each documentation comment should be a summary sentence that contains 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 block tag\&. The \f3javadoc\fR command copies this first sentence to the member summary at the top of the HTML page\&. +.PP +Multiple-Field Declarations + +The Java platform lets you declare multiple fields in a single statement, but this statement can have only one documentation comment that is copied for all fields\&. If you want individual documentation comments for each field, then declare each field in a separate statement\&. For example, the following documentation comment does not make sense written as a single declaration and would be better handled as two declarations: +.sp +.nf +\f3/** \fP +.fi +.nf +\f3 * The horizontal and vertical distances of point (x,y)\fP +.fi +.nf +\f3 */\fP +.fi +.nf +\f3public int x, y; // Avoid this \fP +.fi +.nf +\f3\fR +.fi +.sp +The \f3javadoc\fR command generates the following documentation from the previous code: +.sp +.nf +\f3public int x\fP +.fi +.nf +\f3\fR +.fi +.sp +The horizontal and vertical distances of point (x, y)\&. +.sp +.nf +\f3public int y\fP +.fi +.nf +\f3\fR +.fi +.sp +The horizontal and vertical distances of point (x, y)\&. +.PP +Use of Header Tags + +When writing documentation comments for members, it is best not to use HTML heading tags such as \f3\fR and \f3
\fR, because the \f3javadoc\fR command creates an entire structured document, and these structural tags might interfere with the formatting of the generated document\&. However, you can use these headings in class and package comments to provide your own structure\&. +.SS METHOD\ COMMENT\ INHERITANCE +The \f3javadoc\fR command allows method comment inheritance in classes and interfaces to fill in missing text or to explicitly inherit method comments\&. Constructors, fields, and nested classes do not inherit documentation comments\&. +.PP +\fINote:\fR The source file for an inherited method must be on the path specified by the \f3-sourcepath\fR option for the documentation comment to be available to copy\&. Neither the class nor its package needs to be passed in on the command line\&. This contrasts with Release 1\&.3\&.\fIn\fR and earlier releases, where the class had to be a documented class\&. +.PP +Fill in Missing Text + +When a main description, or \f3@return\fR, \f3@param\fR, or \f3@throws\fR tag is missing from a method comment, the \f3javadoc\fR command copies the corresponding main description or tag comment from the method it overrides or implements (if any)\&. See Method Comment Inheritance\&. +.PP +When an \f3@param\fR tag for a particular parameter is missing, the comment for that parameter is copied from the method further up the inheritance hierarchy\&. When an \f3@throws\fR tag for a particular exception is missing, the \f3@throws\fR tag is copied only when that exception is declared\&. +.PP +This behavior contrasts with Release 1\&.3 and earlier, where the presence of any main description or tag would prevent all comments from being inherited\&. +.PP +See Javadoc Tags and Options\&. +.PP +Explicit Inheritance + +Insert the \f3{@inheritDoc}\fR inline tag in a method main description or \f3@return\fR, \f3@param\fR, or \f3@throws\fR tag comment\&. The corresponding inherited main description or tag comment is copied into that spot\&. +.SS CLASS\ AND\ INTERFACE\ INHERITANCE +Comment inheritance occurs in all possible cases of inheritance from classes and interfaces: +.TP 0.2i +\(bu +When a method in a class overrides a method in a superclass +.TP 0.2i +\(bu +When a method in an interface overrides a method in a superinterface +.TP 0.2i +\(bu +When a method in a class implements a method in an interface +.PP +In the first two cases, the \f3javadoc\fR command generates the subheading \fIOverrides\fR in the documentation for the overriding method\&. A link to the method being overridden is included, whether or not the comment is inherited\&. +.PP +In the third case, when a method in a specified class implements a method in an interface, the \f3javadoc\fR command generates the subheading \fISpecified by\fR in the documentation for the overriding method\&. A link to the method being implemented is included, whether or not the comment is inherited\&. +.SS METHOD\ COMMENTS\ ALGORITHM +If a method does not have a documentation comment, or has an \f3{@inheritDoc}\fR tag, then the \f3javadoc\fR command uses the following algorithm to search for an applicable comment\&. The algorithm is designed to find the most specific applicable documentation comment, and to give preference to interfaces over superclasses: +.TP 0.4i +1\&. +Look in each directly implemented (or extended) interface in the order they appear following the word \f3implements\fR (or \f3extends\fR) in the method declaration\&. Use the first documentation comment found for this method\&. +.TP 0.4i +2\&. +If Step 1 failed to find a documentation comment, then recursively apply this entire algorithm to each directly implemented (or extended) interface in the same order they were examined in Step 1\&. +.TP 0.4i +3\&. +When Step 2 fails to find a documentation comment and this is a class other than the \f3Object\fR class, but not an interface: +.RS +.TP 0.4i +1\&. +If the superclass has a documentation comment for this method, then use it\&. +.TP 0.4i +2\&. +If Step 3a failed to find a documentation comment, then recursively apply this entire algorithm to the superclass\&. +.RE + +.SH JAVADOC\ TAGS +The \f3javadoc\fR command parses special tags when they are embedded within a Java documentation comment\&. The \f3javadoc\fR tags let you autogenerate a complete, well-formatted API from your source code\&. The tags start with an at sign (\f3@\fR) and are case-sensitive\&. They must be typed with the uppercase and lowercase letters as shown\&. A tag must start at the beginning of a line (after any leading spaces and an optional asterisk), or it is treated as text\&. By convention, tags with the same name are grouped together\&. For example, put all \f3@see\fR tags together\&. For more information, see Where Tags Can Be Used\&. +.PP +Tags have the following types: +.TP 0.2i +\(bu +Bock tags: Place block tags only in the tag section that follows the description\&. Block tags have the form: \fI@tag\fR\&. +.TP 0.2i +\(bu +Inline tags: Place inline tags anywhere in the main description or in the comments for block tags\&. Inline tags are enclosed within braces: \fI{@tag}\fR\&. +.PP +For custom tags, see -tag tagname:Xaoptcmf:"taghead"\&. See also Where Tags Can Be Used\&. +.SS TAG\ DESCRIPTIONS +.TP +@author \fIname-text\fR +Introduced in JDK 1\&.0 + +Adds an Author entry with the specified name text to the generated documents when the \f3-author\fR option is used\&. A documentation comment can contain multiple \f3@author\fR tags\&. You can specify one name per \f3@author\fR tag or multiple names per tag\&. In the former case, the \f3javadoc\fR command inserts a comma (,) and space between names\&. In the latter case, the entire text is copied to the generated document without being parsed\&. Therefore, you can use multiple names per line if you want a localized name separator other than a comma\&. See @author in How to Write Doc Comments for the Javadoc Tool at http://www\&.oracle\&.com/technetwork/java/javase/documentation/index-137868\&.html#@author +.TP +{@code \fItext\fR} +Introduced in JDK 1\&.5 + +Equivalent to \f3
{@literal}
\fR\&. + +Displays text in code font without interpreting the text as HTML markup or nested Javadoc tags\&. This enables you to use regular angle brackets (< and >) instead of the HTML entities (\f3<\fR and \f3>\fR) in documentation comments, such as in parameter types (\f3