Generate API Document for Java Package

Java Tools Tutorials - Herong's Tutorial Examples

∟Generate API Document for Java Package

This section provides a tutorial example of how to add javadoc-style comments in Java classes in a packag, add package.html, and generate the API document for the package.

In previous tutorials, we have learned how to generate API document for a single Java class. Now let's try to generate an API document for a package of multiple classes.

1. Create source code of the first class in the package, Point.java:

herong$ vi ./src/com/herongyang/geometry/Point.java

package com.herongyang.geometry;

/**
 * A simple class to represent a point in space.
 * @author Herong Yang
 */
public class Point {

  /**
   * Y-coordinate of the Point.
   */
  public double x = 0.0;

  /**
   * Y-coordinate of the Point.
   */
  public double y = 0.0;

  /**
   * Creates a Point with X- and Y-coordinates.
   * @param x The X-coordinate of the new Point.
   * @param y The Y-coordinate of the new Point.
   */
  public Point(double x, double y) {
    this.x = x;
    this.y = y;
  }

  /**
   * Calculates the distance to another Point.
   * @param p The other Point.
   * @return The distance of this Point and the other Point.
   */
  public double distance(Point p) {
     return Math.sqrt((p.x-x)*(p.x-x)+(p.y-y)*(p.y-y));
  }

  /**
   * Tests the class functionalities
   * @param a The argument array.
   */
  public static void main(String[] a) {
    Point p = new Point(1, 0);
    Point q = new Point(0, 1);
    System.out.println("Point p = ("+p.x+", "+p.y+")");
    System.out.println("Point q = ("+q.x+", "+q.y+")");
    System.out.println("Distance from p to q = "+p.distance(q));
  }
}

2. Create source code of the second class in the package, Vector.java:

herong$ vi ./src/com/herongyang/geometry/Vector.java

package com.herongyang.geometry;
import com.herongyang.geometry.Point;

/**
 * A simple class to represent a vector in space.
 * @author Herong Yang
 */
public class Vector {

  /**
   * X-component of the Vector.
   */
  public double x = 1.0;

  /**
   * Y-component of the Vector.
   */
  public double y = 0.0;

  /**
   * Creates a Vector with X- and Y-components.
   * @param x The X-component of the new Vector.
   * @param y The Y-component of the new Vector.
   */
  public Vector(double x, double y) {
    this.x = x;
    this.y = y;
  }

  /**
   * Creates a Vector with 2 Points.
   * @param f The From-Point of the new Vector.
   * @param t The To-Point of the new Vector.
   */
  public Vector(Point f, Point t) {
    this.x = t.x - f.x;
    this.y = t.y - f.y;
  }

  /**
   * Calculates the length of the Vector.
   * @return The length of this Vector.
   */
  public double length() {
    return Math.sqrt(x*x + y*y);
  }

  /**
   * Calculates the dot-product with another Vector.
   * @param v The other Vector.
   * @return The dot-product of this Vector and the other Vector.
   */
  public double dotProduct(Vector v) {
    return v.x*x + v.y*y;
  }

  /**
   * Tests the class functionalities
   * @param a The argument array.
   */
  public static void main(String[] a) {
    Vector p = new Vector(1, 0);
    Vector q = new Vector(0, 1);
    double dot = p.dotProduct(q);
    System.out.println("Vector p = ("+p.x+", "+p.y+")");
    System.out.println("Vector q = ("+q.x+", "+q.y+")");
    System.out.println("p.q = ("+dot+")");
  }
}

3. Compile the package:

herong$ javac -d ./cls ./src/com/herongyang/geometry/*.java

herong$ tree ./cls

./cls
|-- com
    |-- herongyang
        |-- geometry
            |-- Point.class
            |-- Vector.class

4. Test the package.

herong$ java -cp ./cls com.herongyang.geometry.Point
  Point p = (1.0, 0.0)
  Point q = (0.0, 1.0)
  Distance from p to q = 1.4142135623730951

herong$ java -cp ./cls com.herongyang.geometry.Vector
  Vector p = (1.0, 0.0)
  Vector q = (0.0, 1.0)
  p.q = (0.0)

5. Add javadoc-style comment for the package, package.html:

herong$ vi ./src/com/herongyang/geometry/package.html

<html>
<body>
A package with two geometry objects: Point and Vector.
</body>
</html>

6. Generate the API document for the package:

herong$ javadoc -d ./doc -cp ./cls -sourcepath ./src -author \
   com.herongyang.geometry

Loading source files for package com.herongyang.geometry...
Constructing Javadoc information...
Standard Doclet version 15+36-1562
Building tree for all the packages and classes...
Generating ./doc/com/herongyang/geometry/Point.html...
Generating ./doc/com/herongyang/geometry/Vector.html...
Generating ./doc/com/herongyang/geometry/package-summary.html...
Generating ./doc/com/herongyang/geometry/package-tree.html...
Generating ./doc/constant-values.html...
Generating ./doc/overview-tree.html...
Generating ./doc/deprecated-list.html...
Building index for all the packages and classes...
Generating ./doc/index-all.html...
Building index for all classes...
Generating ./doc/allclasses-index.html...
Generating ./doc/allpackages-index.html...
Generating ./doc/index.html...
Generating ./doc/help-doc.html...