Javadoc Comments

A doc tag is a command inside a Javadoc comment, identified by a name that begins with @.

Programming

A Comment That Describes Its Method

Imagine you are a new team member who has never seen a particular method. Above it sits a comment with a few lines that begin with a special marker. Those marked lines usually give you information that a plain English sentence would not give as cleanly, because each one names a specific part of the method. This article is about those marked lines, which are called doc tags, and about how to read them and check them.

What do you think happens?

Before reading further, which part of a method do you think a line beginning with @param describes?

The name of the method
One of the inputs the method receives
The value the method sends back
The class the method belongs to

Reveal answer

Answer:

One of the inputs the method receives

The @param tag documents a parameter, which is an input to a subroutine. The other tags cover the return value, the exceptions, and, for @author, the class.

Recognizing a Doc Tag

Definition

A doc tag is a command inside a Javadoc comment, identified by a name that begins with @. The @ character is the signal. When you see it at the start of a line inside a documentation comment, you are looking at a tag rather than ordinary words.

A Javadoc comment can also contain HTML commands, so doc tags sit alongside ordinary markup in the same comment. The tags are not the only thing in the comment, but they are the part that tells you which piece of the program each line is about. This article limits the discussion to four tags: @author, @param, @return, and @throws. Each one has its own shape, and the order of the words within that shape is what carries the meaning.

Matching Each Tag to What It Documents

It helps to group the four tags by their target. The @author tag documents a class. The other three document a subroutine, which is a method in the sense used in most Java code, and each one answers a different question about that subroutine. @param answers what goes in. @return answers what comes out. @throws answers what can go wrong.

Which part of the method or class does each tag describe: the class itself, the inputs, the return value, or the exceptions?

Notice that @author sits on the class side of the picture and the other three sit on the subroutine side. A single class can contain many subroutines, so a class-level author line tells you who wrote the class, while each subroutine's tags tell you about that one method. The distinction matters when you read a comment, because a tag belongs to whatever it is attached to, and you should check that the target is the right kind of thing.

Reading the Shape of a Tag

Each tag has a leading @, a tag name, and then whatever the tag needs. For @param, the next word is the name of the parameter being documented, and the rest of the line is the description. The name is the argument that tells you which input the sentence refers to. The description explains what that input means. Reading the word order slowly is the whole skill, because the tag name tells you the category and the word after it tells you the specific item.

What are the parts of a tag like @param count description, and which part is the tag name versus the argument?

@return and @throws follow the same leading-@ pattern, but they do not name a parameter. @return is followed by a description of the value sent back. @throws is followed by the kind of exception the subroutine can raise, then a description of the situation that causes it. Because the tag name is always first, you can scan a comment for lines starting with @ and sort them into these four groups before you read any of the words that follow.

Tracing a Comment Against Its Method

java

/**
 * Returns the total cost of an item after tax.
 * @param price the cost before tax
 * @param taxRate the tax rate as a decimal, such as 0.08
 * @return the price with tax added
 */
public double totalCost(double price, double taxRate) {
    return price + price * taxRate;
}

/**
 * Returns the total cost of an item after tax.
 * @param price the cost before tax
 * @param taxRate the tax rate as a decimal, such as 0.08
 * @return the price with tax added
 */
public double totalCost(double price, double taxRate) {
    return price + price * taxRate;
}

Notes on the code

The description sits first, before any tag.
Each @param name matches a parameter in the signature.
@return appears because totalCost is not void.
No @throws tag, because the body throws no exception.

Worked example

Checking each tag against the signature

Does every tag in the comment above agree with the method it sits on?

1
Start with the return type
The signature declares double, which is not void, so @return is required and is present. The description says the price with tax added, which matches a computed double.
2
Check the parameter list
The signature has two parameters, price and taxRate. The comment has two @param tags naming price and taxRate. Each tag names a real parameter.
3
Check for exceptions
The body only performs arithmetic and returns. Nothing in it throws an exception, so the absence of @throws is consistent with the code.
4
Confirm placement
All tags come after the one-line description, as the placement rule requires.

Result

Every tag agrees with the subroutine it sits in, so the comment has no mismatch to report.

Where Tags Go in a Comment

Think of a subroutine's Javadoc comment as having two parts. The first part is a description of the subroutine itself. The second part is a run of doc tags describing its inputs, its output, and its failures. The tags go at the end of the comment, after any description. The source states that placement rule directly, and it is the only placement rule it gives.

A description can run across several lines. It ends at the next doc tag or at the end of the comment, so no special closing marker is needed for a long explanation. This is why a multi-line @param description is read as one unit even though it spans several physical lines. The reader's eye may wrap, but the tag's meaning does not break at the line end.

Finding a Mismatch Step by Step

When a documentation comment looks wrong, the most useful question is where the mismatch sits. Rather than rereading the whole comment, compare each tag with the subroutine it belongs to. Start with the return type, then the parameter list, then the exceptions the body can throw. A tag that names something the signature does not have is the place where the divergence starts.

Does each @param name match a real parameter in the signature? Here the comment names a and count, but the signature declares a and b.

In the comparison above, the @param a tag lines up with the parameter a and is correct. The @param count tag has no matching parameter, because the signature declares b in that position. That unmatched tag is the mismatch. The fix is either to rename the tag to b and rewrite its description, or to correct the signature if count was the intended name. Checking names one at a time like this is faster than rereading the whole comment.

Common mistake
Adding @return to a void subroutine
What it looks like
A method declared void whose comment still has a @return line describing a value.
Why it fails
@return belongs only on non-void subroutines, so the tag describes a value the method never sends back.
Do this instead
Remove the @return line, or change the signature if the method was meant to return something.
Common mistake
Naming a parameter that does not exist
What it looks like
A comment with @param count when the signature declares b.
Why it fails
A tag that names something the signature does not have is the point where the comment and code diverge.
Do this instead
Rename the tag to match the real parameter, and rewrite its description to fit that parameter.
Common mistake
Putting a tag above the description
Why it fails
The source places the tags at the end of the comment, after any description of the subroutine.
Do this instead
Move the description to the top and place the tags beneath it.
Common mistake
Treating a fixed tag order as required

Relating @throws to the Code That Throws

The @throws tag describes an exception that a subroutine can raise. Its job is to tell the reader that a failure can leave the method, so a caller knows it may need to handle that situation. When you check a @throws tag, the question is whether the body of the subroutine can actually produce that exception. A @throws line for an exception the body never raises is a mismatch of the same kind as a misnamed parameter.

Practice Checking a Comment

EASY

A method public int square(int n) has the Javadoc comment line @param x the number to square and @return the square of the input. Which tag is the mismatch, and what is the fix?

Hints

Start with the parameter list: the signature declares n, not x.
Ask which tag names something the signature does not have.
The fix is either to rename @param x to @param n or to rename the parameter in the signature.

Your attempt (not saved)

Key Takeaways

A doc tag is a command inside a Javadoc comment, identified by a name that begins with @.
@author documents a class, while @param, @return, and @throws document a subroutine's inputs, output, and failures.
@return belongs only on non-void subroutines, and tags go at the end of the comment after the description.
Tags can appear in any order, so when a comment looks wrong, check each tag against the subroutine it sits in, starting with the return type, then the parameters, then the exceptions.