Java : Javadoc

Javadocs Introduction

What is a Javadoc?

Javadocs allow you to generate HTML documentation from your source files. The online API documentation is the result of running a javadoc on the source code of a standard Java library, much like this HTML page here.

Declaring Javadocs

To declare a comment as a Javadoc, simply use one of the following notations:

/** Javadoc Comments */
/**
 Javadoc Comments 
 */
/** 
 *
 *  Javadoc Comments
 *
 */

Anything that goes within these comments are valid for Javadoc. To attach the comments to our code, we place them directly before classes, constructors fields, interfaces and methods.

Javadoc Tags

Tags allow Javadoc to know what type of information will follow. Here is a list of common pre-defined tags:

@author [name]

The Author(s) for a class or interface.

@version [version]

The version of the class.

@param [name][desc]

describes an argument of a method or constructor.

@return [description]

Describes the data that is to be returned.

@exception [exc][desc]

Describes what exception can be thrown by method.

@since [version]

Which version you added this method.

@deprecated [desc]

Use if method or class is deprecated.

@see [hyperlink]

Reference some other javadoc.

Now that we know the fundamentals of declaring a javadoc and the tags that go with, let's learn how to apply them to a typical class.

Applying Javadocs

Description

The first sentence of a Javadoc comment is the description.

/** 
 * The first sentence is the summary statement.
 * <p>
 * We can use HTML modifiers in the free-form text such as <em></em>,
 * <strong></strong> and <img ..>.
 * This is where the longer descriptions would go.
 * </p>
 * However, stray away from the <h1></h1> rules, as they can 
 * interfere with the layout of the published page.
 *
 */

Note that we can also use some HTML elements to change the styling of certain texts.

Class Comments

Place any class comments after the import statements. We use tags to describe parameters. They are followed by a @ symbol. The most common class comments are @author and @version.

/** 
 * A Car Object.
 * 
 * A Car object contains the parameters and functionality of
 * an automobile with four wheels.
 *
 * @author Code Snipcademy 
 * @version 1.0.0 Dec 25, 2015
 */
public class Car {
}

Constructor Comments

For a constructor comment, we want to place an @param with any variables that may be passed to construct an object.

/**
 * Car constructor.
 * 
 * @param numWheels The number of wheels on the car
 */
Car(int numWheels) {
  this.numWheels = numWheels;
}

Method Comments

In a method comment, we may need the @param, @return, @throws and @exception tags.

/**
 * Speed up Car.
 * 
 * @param byMPH The amount in mph to increase car speed
 * @return the now-current car speed
 */
public double speedUp(int byMPH){
} 

Field Comments

Generally, you should document public static fields.

/**
 * The number of wheels on a car. 
 */
public static final int numWheels = 4;

With these javadoc comments in place, we should now be ready to compile and generate our HTML files!

Compiling a Javadoc

Compiling is as easy as a single comment. As an example, we'll compile the bottom code object Car. We can do this easily with the javadoc command.

$ javadoc -d CarHTML Car.java

Javadoc Options

Here are some options you may find helpful.

-author

Includes an author section.

-classpath [path]

Specifies where to search for a references .class file.

-d [path]

Specifies where to generate the document.

-version

Generated documentation includes a version section.

-private

Generated documentation includes private fields and methods.

/**
 * A Car object contains the parameters and functionalities of
 * a basic automobile. 
 *
 * @author CodeSnipcademy
 * @version 4.0.0 Dec 26, 2014.
 */
public class Car {
   /**
    * The number of wheels on any car.
    */ 
    public static final int numWheels = 4;
    private String make;
    private String model;
    private String color;
    private int yearBuilt;
    private int currentSpeed;
   /** 
    * Default constructor for car.
    *
    * Sets to most generic car model.
    *
    */
    Car () {
        this.make = "Toyota";
        this.model = "Camry";
        this.color = "silver";
        this.yearBuilt = 2000;
    }
   /** 
    * Constructor that makes a Car object according to specifics.
    *
    * @param make Manufacturer
    * @param model Model of car
    * @param yearBuilt Year that car was made
    * @param color Color of car 
    */
    Car (String make, String model, String yearBuilt, String     | color) {
        this.make = make;
        this.model = model;
        this.color = color;
        this.yearBuilt = yearBuilt;
    }
   /**
    * Get the make of car.
    * @return car Make
    */
    public String getMake() { return make; }
   /**
    * Get the model of car.
    * @return car Model
    */
    public String getModel() { return model; }
   /**
    * Get the color of car.
    * @return car Color
    */
    public String getColor() { return color; }
   /**
    * Get the year of car.
    * @return car Year
    */
    public int getYear() { return year; } 
   /**
    * Speed up the car's current driving pace.
    * @param increment Amount to speed up by
    * @return currentSpeed The now currentSpeed
    */
    public int speedUp(int increment) {
        currentSpeed += increment;
        return currentSpeed;
    }
   /**
    * Slow up the car's current driving pace.
    * @param decrement Amount to slow down by
    * @return currentSpeed The now currentSpeed
    */
    public int slowDown(int decrement) {
        currentSpeed -= decrement;
        return currentSpeed;
    }
   /**
    * Play tape player.
    * @deprecated People don't listen to tapes anymore
    * @param cassetteName Name of tape to play
    */
    public void playTape(String cassetteName) {
            
    }
   /**
    * Turns on AUX cable.
    * @since version 2.0.0
    * @param inputGadget The gadget that is being plugged in
    */
    public void playAux(String inputGadget) {
    }
}