Java Reference
In-Depth Information
19.5. External Conventions
Not all documentation needed for a package can be ascribed to a specific
source file, nor are source files the only types of files that need to be re-
ferred to in documentation. You can incorporate such external elements
in your documentation.
19.5.1. Package and Overview Documentation
Doc comments associate documentation with elements in source files,
but packages are not defined in source files. The
javadoc
tool uses other
conventions to allow packages to be documented.
The preferred mechanism, as mentioned in
Section 18.5
on page
476
, is
to use the
package-info.java
file. This file should contain a single
package
statement identifying the package to which the file belongs, together with
all annotations that apply to the package. In addition, if that package
statement (with its applied annotations if any) is preceded by a doc com-
ment, then that doc comment is treated as documentation for the overall
package. This package documentation forms part of the package sum-
mary page that is produced by
javadoc
.
If there is no
package-info.java
file for a package, then
javadoc
will look
for a file called
package.html
. If this file exists, then its contents between
<body>
and
</body>
will be read as if it were a doc comment for the pack-
age (although it should not have the
/**
,
*/
, or any leading
*
). Note that
package.html
will be ignored if
package-info.java
exists.
As with other doc comments, the first sentence of the package comment
is used as a summary for the package. In the case of
package.html,
this
is the first sentence after the
<body> HTML
tag. Any
@see
or
{@link}
tag that
names a language element must use the fully qualified form of the en-
tity's name, even for classes and interfaces within the package itself.
Finally, you can also provide an overview
HTML
file. An overview
HTML
file
is read in the same way as a
package.html
file, and it can contain docu-
