Java Reference
In-Depth Information
com/jdojo/utility/package.html file
It is a regular HTML file with HTML tags. The HTML contents within the
<body>
and
</body>
tags is used as the
package documentation. It does not contain a package declaration. It does not use
/**
and
*/
characters as start and
end of the documentation comment. However, you can use documentation tags that are valid for the package. The
content of the
package.html
file for
com.jdojo.utility
package is as shown:
<html>
<body>
Contains utility classes. More description for
com.jdojo.utility package goes here.
@since 1.1
@version 1.9
</body>
</html>
Overview Documentation
The overview documentation is used to write documentation for the entire application in a separate HTML file.
There is no rule for naming the overview documentation file. Generally, the overview documentation file is named
as
overview.html
. The comment is placed inside the
<body>
and
</body>
tags in the HTML file. You need to pass the
path of the overview documentation comment file to the
javadoc
tool using the
-overview
command-line option.
The following is a sample overview comment contained in an HTML file:
<html>
<body>
API documentation for the dummy application. More overview text goes here.
@author Who Knows
@version 1.2
</body>
</html>
Including Unprocessed Files in Documentation
Sometimes you may want to include some files with your Java documentation, which you reference inside the
documentation comments. For example, you may want to display graphics or source code. The
javadoc
tool lets you
include files, which it copies to the generated documentation directory without processing them. You need to create
a directory called
doc-files
under any package directory that contains
.java
source files, and copy your extra files in
that directory. The
javadoc
tool will copy all your files to the destination directory without processing them.
Skipping Source Files Processing
Sometimes you may have some Java source files that you do not want the
javadoc
tool to process. For example, you
may have some test files for which you do not want to generate documentation. The
javadoc
tool looks at the file name
before it decides to process the content of the file. If the file name is not a valid Java identifier, it skips that file. If you
have a
.java
source file, which
javadoc
tool should skip, you need to name that file such that the name is not a valid
Java identifier. For example, you may include a hyphen (-) in the file name to skip it. Note that this strategy of skipping
source file processing is needed when you are using
javadoc
tool to generate documentation by passing it wildcards (
*
)
or package name. If you supply the
javadoc
tool the list of source files to process, you do not need to use this strategy.