[Reference]javadoc的使用实例

文献出处: http://java.sun.com/j2se/1.5.0/docs/tooldocs/windows/javadoc.html#examples

SIMPLE EXAMPLES

You can run javadoc on entire packages or individual source files. Each package name has a corresponding directory name. In the following examples, the source files are located at C:/home/src/java/awt/*java. The destination directory is C:/home/html.

Documenting One or More Packages

To document a package, the source files ( *.java) for that package must be located in a directory having the same name as the package. If a package name is made up of several identifiers (separated by dots, such as java.awt.color), each subsequent identifier must correspond to a deeper subdirectory (such as java/awt/color). You may split the source files for a single package among two such directory trees located at different places, as long as -sourcepath points to them both -- for example src1/java/awt/color and src2/java/awt/color.

You can run javadoc either by changing directories (with cd) or by using -sourcepath option. The examples below illustrate both alternatives.

• Case 1 - Run recursively starting from one or more packages - This example uses -sourcepath so javadoc can be run from any directory and -subpackages (a new 1.4 option) for recursion. It traverses the subpackages of the java directory excluding packages rooted at java.net and java.lang. Notice this excludes java.lang.ref, a subpackage of java.lang).

    % javadoc -d /home/html -sourcepath /home/src -subpackages java -exclude java.net:java.lang
  

  To also traverse down other package trees, append their names to the -subpackages argument, such as java:javax:org.xml.sax.

   

• Case 2 - Run on explicit packages after changing to the "root" source directory - Change to the parent directory of the fully-qualified package. Then run javadoc, supplying names of one or more packages you want to document:

    C:> cd C:/home/src/
    C:> javadoc -d C:/home/html java.awt java.awt.event
  

• Case 3 - Run from any directory on explicit packages in a single directory tree - In this case, it doesn't matter what the current directory is. Run javadoc supplying -sourcepath with the parent directory of the top-level package, and supplying names of one or more packages you want to document:

    C:> javadoc -d C:/home/html -sourcepath C:/home/src java.awt java.awt.event
  

• Case 4 - Run from any directory on explicit packages in multiple directory trees - This is the same as case 3, but for packages in separate directory trees. Run javadoc supplying -sourcepath with the path to each tree's root (colon-separated) and supply names of one or more packages you want to document. All source files for a given package do not need to be located under a single root directory -- they just need to be found somewhere along the sourcepath.

    C:> javadoc -d C:/home/html -sourcepath C:/home/src1;C:/home/src2 java.awt java.awt.event
  

Result: All cases generate HTML-formatted documentation for the public and protected classes and interfaces in packages java.awt and java.awt.event and save the HTML files in the specified destination directory ( C:/home/html). Because two or more packages are being generated, the document has three HTML frames -- for the list of packages, the list of classes, and the main class pages.

Documenting One or More Classes

The second way to run the Javadoc tool is by passing in one or more source files ( .java). You can run javadoc either of the following two ways -- by changing directories (with cd) or by fully-specifying the path to the .java files. Relative paths are relative to the current directory. The -sourcepath option is ignored when passing in source files. You can use command line wildcards, such as asterisk (*), to specify groups of classes.

• Case 1 - Changing to the source directory - Change to the directory holding the .java files. Then run javadoc, supplying names of one or more source files you want to document.

    C:> cd C:/home/src/java/awt
    C:> javadoc -d C:/home/html Button.java Canvas.java Graphics*.java
  

  This example generates HTML-formatted documentation for the classes Button, Canvas and classes beginning with Graphics. Because source files rather than package names were passed in as arguments to javadoc, the document has two frames -- for the list of classes and the main page.

   

• Case 2 - Changing to the package root directory - This is useful for documenting individual source files from different subpackages off the same root. Change to the package root directory, and supply the source files with paths from the root.

    C:> cd C:/home/src
    C:> javadoc -d /home/html java/awt/Button.java java/applet/Applet.java
  

  This example generates HTML-formatted documentation for the classes Button and Applet.

   

• Case 3 - From any directory - In this case, it doesn't matter what the current directory is. Run javadoc supplying the absolute path (or path relative to the current directory) to the .java files you want to document.

    C:> javadoc -d C:/home/html C:/home/src/java/awt/Button.java C:/home/src/java/awt/Graphics*.java
  

  This example generates HTML-formatted documentation for the class Button and classes beginning with Graphics.

Documenting Both Packages and Classes

You can document entire packages and individual classes at the same time. Here's an example that mixes two of the previous examples. You can use -sourcepath for the path to the packages but not for the path to the individual classes.

  C:> javadoc -d C:/home/html -sourcepath C:/home/src java.awt C:/home/src/java/applet/Applet.java

This example generates HTML-formatted documentation for the package java.awt and class Applet. (The Javadoc tool determines the package name for Applet from the package declaration, if any, in the Applet.java source file.)