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 comment, then that doc comment is treated as documentation for the
overall package. This package documentation forms part of the package summary 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
packagtemp0282.html. If this file exists, then its contents between
as if it were a doc comment for the package (although it should not have the /*, /, or any leading *). Note
that packagtemp0282.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 packagtemp0282.html, this is the first sentence after the
or {@link} tag that names a language element must use the fully qualified form of the entity'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
packagtemp0282.html file, and it can contain documentation for a set of packages or classes, giving an
overview of what they do. You specify the HTML file to use as an overview when generating the
documentation.
19.5.2. The doc-files Directory
The javadoc program will copy the contents of a doc-files directory in a given package into the
generated documentation for that package. You can use this feature to include images, HTML, class files, or
any other component you want to reference in your doc comment. For example, you could indirectly include a
set of formal rules in a large number of doc comments:
@see Formal Semantics
Or you could use the directory to store useful images:
Made by Magic, Inc.
19.6. Notes on Usage
Tightly coupling the reference documentation to the source code has many advantages, but it does not turn all
programmers into good documentation writers. Programmers will continue to vary in their ability and interest
in writing good reference documentation. Many organizations have technical writers to produce the reference