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.
 
Search WWH ::




Custom Search