Java Reference
In-Depth Information
The tool generates one HTML file per class/interface/enum/annotation. The files are placed in directories that
mimic the package hierarchies of classes, interfaces, enums, and annotations. The file names are the same as the
program elements for which they contain the documentation. A
package-summary.html
file is included in every
package directory that contains package documentation. An
overview-summary.html
file is generated for all packages
to serve as overview documentation.
The generated HTML pages include the class hierarchy pages, a deprecated API page, constants values pages,
serialized forms pages, etc. These files have self-explanatory names and they contain a hyphen in their names.
Support files include any image files, a
help-doc.html
file to describe the generated documentation files, etc.
Viewing Generated HTML Documentation
You can view the documentation generated by the
javadoc
tool in an HTML page using HTML frames or with no
frames. The
javadoc
tool generates two files,
index.html
and
overview-summary.html
, which are placed at the root
in the output directory. You need to open the
index.html
file in a browser, for example, Microsoft Internet Explorer,
Google Chrome, Mozilla Firefox, Safari, etc., to view the documentation using HTML frames. You can open the
overview-summary.html
file in a browser to view the documentation without HTML frames. The HTML frames are
organized as shown in Figure
B-2
.
Packages
Details
Classes
Figure B-2.
Arrangement of the HTML frames that are generated by the javadoc tool
The
index.html
page has three frames. The upper-left frame contains the list of packages. If the documentation
that you generate belongs to only one package, this frame is not generated. That is, you must generate documentation
for at least two packages in order for the
javadoc
tool to generate the Packages frame. The lower-left frame contains
the list of classes, interfaces, enums, exceptions, and annotations in a package that is selected from the Packages
frame. The frame on the right side displays the details of the selection from the left frames.
Summary
Java allows writing comments in source code that can be used to generate documentation. The documentation
comment starts with /** and ends with */. The
javadoc
tool, which is included in the JDK is used to extract and
generate the documentation comments from source code. The tool generates documentation in HTML format.
The tool contains support for many custom tags with special meaning. It also lets you use HTML tags inside
the documentation.
