02. 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!

Learn Enterprise Java Development for a Bright Career

Core Java, Volume I

Learn Enterprise Java Development for a Bright Career Try Java

Designed for serious programmers, this reliable, unbiased, no-nonsense tutorial illuminates key Java language and library features with thoroughly tested code examples. As in previous editions, all code is easy to understand, reflects modern best practices, and is specifically designed to help jumpstart your projects.

$ Check price
59.9959.99Amazon 4.5 logo(70+ reviews)

More Java resources

Take your Linux skills to the next level!

Linux for Beginners

Take your Linux skills to the next level! Try Linux & UNIX

Linux for Beginners doesn't make any assumptions about your background or knowledge of Linux. You need no prior knowledge to benefit from this book. You will be guided step by step using a logical and systematic approach. As new concepts, commands, or jargon are encountered they are explained in plain language, making it easy for anyone to understand.

$ Check price
24.9924.99Amazon 4.5 logo(101+ reviews)

More Linux & UNIX resources

Ad