1. apidoc
2. documenting APIs
3. Native library APIs

Javadoc tags

Javadoc is a document generator that looks through your Java source files for specific annotations. It parses out the annotations into the Javadoc output. Knowing the annotations is essential because this is how the Javadoc gets created.

• Comments versus Javadoc tags
• Common Javadoc tags
• What elements you add Javadoc tags to
• Public versus private modifiers and Javadoc
• The description
• Avoid @author
• Order of tags
• @param tags
• @return tags
• @throws tags
• Doc comments for constructors
• Doc comments for fields
• Cases where you don’t need to add doc comments
• @see tags
• Links
• Previewing Javadoc comments
• Why all the detail about Javadoc tags?
• More information about Javadoc

Comments versus Javadoc tags

A general comment in Java code is signaled like this:

// sample comment...

/*
sample comment
*/

Javadoc does nothing with these comments.

To include content in Javadoc, you add two asterisks at the start, before the class or method:

/**
*
*
*
*
*/

(In Eclipse, if you type /** and hit return, it autofills the rest of the syntax automatically.)

The format for adding the various elements is like this:

/**
* [short description]
* <p>
* [long description]
*
* [author, version, params, returns, throws, see, other tags]
* [see also]
*/

Here’s a real example of Javadoc comments for a method.

/**
* Zaps the roadrunner with the number of volts you specify.
* <p>
* Do not exceed more than 30 volts or the zap function will backfire.
* For another way to kill a roadrunner, see the {@link Dynamite#blowDynamite()} method.
*
* @exception IOException if you don't enter a data type amount for the voltage
* @param voltage the number of volts you want to send into the roadrunner's body
* @see #findRoadRunner
* @see Dynamite#blowDynamite
*/
public void zapRoadRunner(int voltage) throws IOException {
   if (voltage < 31) {
       System.out.println("Zapping roadrunner with " + voltage + " volts!!!!");
   }
   else {
    System.out.println("Backfire!!! zapping coyote with 1,000,000 volts!!!!");
   }
}

You put the Javadoc description and tags before the class or method (no need for any space between the description and class or method).

Common Javadoc tags

The following are the most common tags used in Javadoc. Each tag has a word that follows it. For example, @param latitude means the parameter is “latitude.”

To view a lengthy example of Javadoc tags, see this example from Oracle.</div>

The following are some common Javadoc tags:

• @author A person who made significant contributions to the code. Applied only at the class, package, or overview level. Not included in the Javadoc output. It’s not recommended to include this tag since authorship changes often.
• @param A parameter that the method or constructor accepts.
• @deprecated Lets users know the class or method is no longer used. This tag will be positioned prominently in the Javadoc. Accompany it with a @see or {@link} tag as well.
• @return What the method returns.
• @see Creates a “see also” list. Use {@link} for the content to be linked.
• {@link} Used to create links to other classes or methods. Example: {@link Foo#bar} links to the method bar that belongs to the class Foo. To link to the method in the same class, just include #bar.
• @since 2.0 The version since the feature was added.
• @throws The kind of exception the method throws. Note that your code must indicate an exception thrown in order for this tag to validate. Otherwise, Javadoc will produce an error. @exception is an alternative tag.
• @Override Used with interfaces and abstract classes. Performs a check to see if the method is an override.

What elements you add Javadoc tags to

You add Javadoc tags to classes, methods, and fields.

• For the @author and @version, add these tags only to classes and interfaces.
• The @param tags get added only to methods and constructors.
• The @return tag gets added only to methods.
• The @throws tag can be added to classes or methods.

Public versus private modifiers and Javadoc

Javadoc includes only classes, methods, etc., marked as public. Elements marked as private are not included in Javadoc unless you specifically select private when generating the Javadoc. If you omit public from your source code, the default is that the class or method is available to the package only. In this case, it is not included in Javadoc.

The description

Javadoc provides both a short and long description. Here’s an example showing how the description part is formatted:

/**
* Short one line description.
* <p>
* Longer description. If there were any, it would be
* here.
* <p>
* And even more explanations to follow in consecutive
* paragraphs separated by HTML paragraph breaks.
*
* @param variable Description text text text.
* @return Description text text text.
*/
public int methodName (...) {
// method body with a return statement
}

(This example comes from Wikipedia entry.)

The short description is the first sentence and gets shortened as a summary for the class or method in the Javadoc. After a period, the parser moves the rest of the description into a long description. Use <p> to signal the start of a new paragraph. You don’t need to surround the paragraphs with opening and closing <p> tags because the Javadoc compiler automatically adds them. Also, you can use HTML in your descriptions, such as an unordered list, code tags, bold tags, or others.

After the descriptions, enter a blank line (for readability) and then start the tags. You can’t add any more description content below the tags. Note that only methods and classes can have tags, not fields. Fields (variables) have descriptions only.

Note that the first sentence is much like the shortdesc element in DITA. This first sentence is supposed to be a summary of the entire class or method. If one of your words has a period in it (like Dr. Jones), then you must remove the space following the period by adding Dr. Jones to connect it.

Avoid using links in the first sentence. After the period, the next sentence shifts to the long paragraph, so you have to load up that first sentence to be descriptive. The verb tense should be present tense, such as gets, puts, displays, calculates…

What if the method is so obvious (for example, printPage) that your description (“prints a page”) becomes redundant and looks useless? Oracle says in these cases, you can omit saying “prints a page” and instead try to offer some other insight. Oracle suggests:

Add description beyond the API name. The best API names are “self-documenting”, meaning they tell you basically what the API does. If the doc comment merely repeats the API name in sentence form, it is not providing more information. For example, if method description uses only the words that appear in the method name, then it is adding nothing at all to what you could infer. The ideal comment goes beyond those words and should always reward you with some bit of information that was not immediately obvious from the API name. – How to write javadoc comments

Avoid @author

Commenting on Javadoc best practices, some people recommend using @author because the author value easily slips out of date, and the source control provides better indication of the last author. (See Javadoc coding standards for more detail.)

Order of tags

Oracle says the order of the tags should be as follows:

@author (classes and interfaces)
@version (classes and interfaces)
@param (methods and constructors)
@return (methods)
@throws (@exception is an older synonym)
@see
@since
@serial
@deprecated

@param tags

@param tags apply only to methods and constructors, both of which take parameters. After the @param tag, add the parameter name, and then a description of the parameter, in lowercase, with no period, like this:

@param url the web address of the site

The parameter description is a phrase, not a full sentence. The order of multiple @param tags should mirror their order in the method or constructor.

Stephen Colebourne recommends adding an extra space after the parameter name to increase readability (and I agree).

As far as including the data type in the parameter description, Oracle says:

By convention, the first noun in the description is the data type of the parameter. (Articles like “a”, “an”, and “the” can precede the noun.) An exception is made for the primitive int, where the data type is usually omitted. (See How to write doc comments using Javadoc.)

The example Oracle gives is as follows:

@param ch the character to be tested

However, the data type is visible from the parameters in the method. So even if you don’t include the data types, it will be easy for users to see what they are.

Note that you can have multiple spaces after the parameter name so that your parameter definitions all line up.

@param tags must be provided for every parameter in a method or constructor. Failure to do so will create an error and warning when you render Javadoc.

Note that usually, classes don’t have parameters. There is one exception: Generics. Generic classes are classes that work with different type of objects. The object is specified as a parameter in the class in diamond brackets: <>. Although the Javadoc guidance from Oracle doesn’t mention them, you can add a @param tag for a generic class to note the parameters for the generic class. See this StackOverflow post for details. Here’s an example from that page:

/**
* @param <T> This describes my type parameter
    */
    class MyClass<T>{

        }

@return tags

Only methods return values, so only methods would receive a @return tag. If a method has void as a modifier, it doesn’t return anything. If it doesn’t say void, then you must include a @return tag to avoid an error when you compile Javadoc.

@throws tags

You add @throws tags to methods or classes only if the method or class throws a particular kind of error. Here’s an example:

@throws IOException if your input format is invalid

Stephen Colebourne recommends starting the description of the throws tag with an “if” clause for readability. He says,

The @throws feature should normally be followed by if ... and the rest of the phrase describing the condition. For example, @throws if the file could not be found. This aids readability in source code and when generated.

If you have multiple throws tag, arrange them alphabetically.

Doc comments for constructors

It’s a best practice to include a constructor in a class. However, if the constructor is omitted, Javadoc automatically creates a constructor in the Javadoc but omits any description of the constructor.

Constructors have @param tags but not @return tags. Everything else is similar to methods.

Doc comments for fields

Fields have descriptions only. You would only add doc comments to a field if the field were something a user would use.

Cases where you don’t need to add doc comments

Oracle says there are three scenarios where the doc comments get inherited, so you don’t need to include comments in these scenarios:

• When a method in a class overrides a method in a superclass
• When a method in an interface overrides a method in a superinterface
• When a method in a class implements a method in an interface
  (See How to write Javadoc comments.)

@see tags

The @see tag provides a see also reference. There are various ways to denote what you’re linking to in order to create the link. If you’re linking to a field, constructor, or method within the same field, use #.

If you’re linking to another class, put that class name first followed by the # and the constructor, method, or field name.

If you’re linking to a class in another package, put the package name first, then the class, and so on. See this sample from Oracle:

@see #field
@see #Constructor(Type, Type...)
@see #Constructor(Type id, Type id...)
@see #method(Type, Type,...)
@see #method(Type id, Type, id...)
@see Class
@see Class#field
@see Class#Constructor(Type, Type...)
@see Class#Constructor(Type id, Type id)
@see Class#method(Type, Type,...)
@see Class#method(Type id, Type id,...)
@see package.Class
@see package.Class#field
@see package.Class#Constructor(Type, Type...)
@see package.Class#Constructor(Type id, Type id)
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type id, Type, id)

For more information, see How to write Javadoc comments.

Links

You can create links to other classes and methods using the {@link} tag.

Here’s an example from Javadoc coding standards on making links:

/**
* First paragraph.
* <p>
* Link to a class named 'Foo': {@link Foo}.
* Link to a method 'bar' on a class named 'Foo': {@link Foo#bar}.
* Link to a method 'baz' on this class: {@link #baz}.
* Link specifying text of the hyperlink after a space: {@link Foo the Foo class}.
* Link to a method handling method overload {@link Foo#bar(String,int)}.
*/
public ...

To link to another method within the same class, use this format: {@link #baz}. To link to a method in another class, use this format: {@link Foo#baz}. However, don’t over hyperlink. When referring to other classes, you can use <code> tags.

To change the linked text, put a word after #baz like this: @see #baz Baz method.

Previewing Javadoc comments

In Eclipse, you can use the Javadoc tab at the bottom of the screen to preview the Javadoc information included for the class you’re viewing.

Why all the detail about Javadoc tags?

I’ve added a lot of specific detail and style guidelines about Javadoc tags here. Why? I wanted you to realize that annotations for the Javadoc follow a lot of style conventions and best practices. These conventions and best practices might not always be apparent or followed in Java files that you might be working on. You can add a lot of value just by making sure the content aligns with these style conventions.

More information about Javadoc

• Oracle’s explanation of Javadoc tags
• Javadoc