Java Tutorial for Python Programmers

Javadoc

In Python, auto-generating documentation can be created from docstrings embedded in the code. Java has a similar system using something called Javadoc. Instead of strings, Javadoc is added using specially-formatted block comments. These comments are sometimes called Javadoc headers and can replace normal comment headers placed above of public member definitions.

Class documentation

Classes are documented by adding a block comment above the class signature. The comment must begin with /** and each line should begin with an *. Here's an example for Monkey.java:

/**
 * Represents a monkey simian.
 *
 * @author Leif Reddington
 */
public class Monkey extends Mammal {

The @author part is called a tag. Each tag takes different "arguments". This one only takes one, but if more are used, they are separated only by spaces.

Generating the Documentation

Like with Pydoc, Javadoc can generate documentation webpages via the command line. Let's try it out!

$ javadoc Monkey.java
Loading source file Monkey.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_79
Building tree for all the packages and classes...
Generating /Monkey.html...
Generating /package-frame.html...
Generating /package-summary.html...
Generating /package-tree.html...
Generating /constant-values.html...
Building index for all the packages and classes...
Generating /overview-tree.html...
Generating /index-all.html...
Generating /deprecated-list.html...
Building index for all classes...
Generating /allclasses-frame.html...
Generating /allclasses-noframe.html...
Generating /index.html...
Generating /help-doc.html...
$ ls *.html
Monkey.html
$

Check out the .html file in a web browser and you'll see a nice API page with your description for the class.

Constant Documentation

Public constants should also enjoy a Javadoc header comment:

    /**
     * The number of ounces in one pound.
     */
    public static final int OUNCES_PER_POUND = 16;

Method Documentation

Only public members should be Javadoc'ed. Methods each deserve a Javadoc comment with tags for each parameter and a tag for the return value (if it's fruitful). Here's what the Javadoc for Mammal's setAge method might look like:

    /**
     * Changes the age of this Mammal.
     *
     * @param age  The new age of this mammal.  If this is less than zero, then the age will be set to zero instead.
     */
    public void setAge(int age) {

Notice that the name of the parameter is included as an argment to the tag. If you don't specify parameter name correctly, Javadoc will notice and will report an error. Here's an example with a return value:

    /**
     * Returns the age of this mammal.
     *
     * @return  The new age of this mammal, in years.
     */
    public int getAge() {

Public constructors need Javadoc too:

    /**
     * Creates a new Monkey.
     *
     * @param age  The age of the monkey, in years.  If a negative argument is provided, this is set to zero instead.
     * @param height  The height of the monkey, in meters.
     * @param name  The name of the monkey.
     */
    public Monkey(int age, double height, String name) {

Add more getters and setters to Monkey.java, then document them and compile the Javadoc to see your awesome documentation pages!

Test Your Understanding

Add Javadoc to your Horse and Zebra classes. Compile the Javadoc and check it out. You'll notice that there's a link from the Zebra page to the Horse superclass page. Sweet!