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) {
}
}