Java Reference
In-Depth Information
The syntax to run the
javadoc
tool is
javadoc <options> <package-names> <source-files-paths> <-subpackages pkg1:pkg2...> <@args-file-paths>
The
<options>
is zero or more command-line options for the javadoc tool. Options are used to customize the
output. For example, a
-d
option lets you specify the output directory where the javadoc tool will store all generated
output files.
The
<package-names>
is a space-separated list of package names. The javadoc tool will generate HTML
documentation pages for all packages that are listed. For example, the value of
com.jdojo.utility
for this argument
will generate documentation pages for source codes that are in the
com.jdojo.utility
package. Note that you must
specify each package name separately for this argument. The
javadoc
tool will not generate documentation for any
subpackages for this argument. You need to use the
-sourcepath
option to specify the locations where the javadoc
tool will look for the source codes for the packages.
The
<source-files-paths>
is a space-separated list of source files paths. You can use the wildcard (*) in the file
paths. For example, you can use
C:\projects\src\com.jdojo\utility\*.java
to generate documentation for all
source files in
C:\projects\src\com.jdojo\utility
directory.
The
<-subpackages pkg1:pkg2...>
lets you specify package names. It is a colon-separated list of package
names. It generates documentation for the specified package names and their subpackages recursively. For example,
the option
-subpackages com.jdojo
will generate documentations for all source code in the
com.jdojo
package and
all of its subpackages, for example,
com.jdojo.utility
,
com.jdojo.chapter2
, etc.
The
<@args-file-paths>
lets you include arguments for the tool in files. Sometimes the comment text for the
javadoc
tool becomes too big. Some command prompts have limitations as to how many characters can be entered
as part of a command. In those circumstances, you can place the command-line arguments in one or more arguments
files and supply those argument file paths as the arguments to the
javadoc
tool. Note that the arguments file path is
preceded by the
@
sign. The
javadoc
tool does not support
-J
options and wildcards (
*
) in an argument file.
■
the javadoc tool provides many options to customize the generated output files. to list all options, you can run it
using the
-help
option, as in
javadoc -help
. You can use a
-J-version
option to print the version of the
javadoc
tool,
as in
javadoc -J-version
.
Tip
I need to discuss the
-sourcepath
option for the
javadoc
tool before you look at some examples of running it.
Sometimes the
javadoc
tool has to find the source files (
.java
files). For example, when you pass the package names or
subpackage names to generate documentation to the
javadoc
tool, it needs to find all files that have the source code for
those packages. By default, the
javadoc
tool uses the CLASSPATH to search for the source files. If the CLASSPATH is not
set, it uses the current directory to search for the source files. The
-sourcepath
option is used to specify the locations
where the
javadoc
tool can search for source files. The package name is concatenated to each entry in the
-sourcepath
value to locate the source files. In Windows, the
-sourcepath
option is a semicolon-separated list of directories,
whereas in UNIX-like operating systems, it is a colon-separated list of directories.
The following command will generate documentation for all source code in the
com.jdojo.utility
package.
It will place the output files in
C:\projects\docs
directory. The argument to the
-sourcepath
option is
src
, which
indicates that the
javadoc
tool will look for the source files (
.java
files) under
C:\projects\src
directory.
C:\projects>javadoc -d docs -sourcepath src com.jdojo.utility
The following command will generate documentation for all source code under
com.jdojo
package and its
subpackages. It will place the output in
C:\projects\docs
directory.
C:\projects>javadoc -d docs -sourcepath src -subpackages com.jdojo
