Search results

Javadoc tags

Chapter 13: Library-based APIs 60% complete

Topic 6 of 10

Last updated: Oct 18, 2026

Download PDF

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

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.”

Sponsored

To view a lengthy example of Javadoc tags, see this example from Oracle.

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. The Javadoc tool leaves it out of the output unless you use the -author option. Many teams avoid 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 or constructor throws. For checked exceptions, the code must declare the exception (with throws) for this tag to validate. Otherwise, Javadoc reports an error. @exception is an older synonym.

(You might also see @Override above methods. Despite the @ symbol, @Override isn’t a Javadoc tag. It’s a Java annotation that tells the compiler to check that the method overrides a method from a superclass or interface.)

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 gets added only to methods and constructors.

Public versus private modifiers and Javadoc

By default, the Javadoc tool includes classes and members marked as public or protected. (In the Eclipse activity, you selected Public, which includes only public elements.) Elements marked as private aren’t included unless you specifically select private when generating the Javadoc. If you omit an access modifier in your source code, the class or member is available to the package only (“package-private”), and it’s left out of the default output.

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 the Wikipedia entry for Javadoc.)

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. Fields mostly have descriptions only, though a few tags, such as @see, @since, and @deprecated, also work on fields.

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.&nbsp;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 Doc Comments for the Javadoc Tool

Avoid @author

Commenting on Javadoc best practices, some people recommend against 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 for the Javadoc Tool.)

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 should be provided for every parameter in a method or constructor. If one is missing, Javadoc shows a warning when you generate the output.

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 Stack Overflow 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 include a @return tag. Otherwise, Javadoc shows a warning when you generate the output.

@throws tags

You add @throws tags to methods or constructors that throw a particular kind of exception. 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

If a class doesn’t define a constructor, Java provides a default one, and Javadoc lists it without a description. (Recent versions of Javadoc also show a warning about the undocumented default 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 Doc Comments for the Javadoc Tool.)

@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 class, 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 Doc Comments for the Javadoc Tool.

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.

Markdown in doc comments

Starting with JDK 23, you can write doc comments in Markdown instead of HTML. (See JEP 467: Markdown Documentation Comments.) Markdown doc comments start each line with three slashes (///) instead of using /** ... */:

/// Rides the bicycle for the given distance.
///
/// Use **kilometers**, not miles. See [#pedal(int)].
///
/// @param distance the distance to ride, in kilometers
/// @throws IOException if the route can't be loaded
public void ride(int distance) throws IOException {
}

The block tags (@param, @throws, and so on) work the same way. Links use square brackets instead of {@link}. Most existing code still uses the traditional HTML style, so you’ll need to know both.

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.

Javadoc pane
Javadoc pane

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

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

© 2026 Tom Johnson