Javadoc Tags

Javadoc tags are structured annotations inside Java documentation comments that describe API details such as parameters, return values, exceptions, and related members. They help generate consistent documentation for classes, methods, and fields.

Javadoc comments use `/** ... */` and can contain prose plus tags beginning with `@`. Tags provide structured information that documentation tools can recognize and present separately from the descriptive text.

For methods, `@param` documents an input parameter, while `@return` describes the value returned by the method. A method that does not return a value, such as one with return type `void`, normally does not need `@return`.

`@throws` documents an exception that a method may throw, including the exception type and a description. `@see` creates a reference to related API documentation, which is useful when readers need additional context.

Javadoc also supports many other tags, including `@author`, `@since`, `@deprecated`, and `@Override` is not a Javadoc tag; it is a Java annotation. Tags should accurately describe the API rather than merely repeat information that is already obvious from the declaration.

Key points

• `@param` documents a method or constructor parameter.
• `@return` describes a method's returned value.
• `@throws` documents an exception a method can throw.
• `@see` points readers toward related API documentation.
• Javadoc tags begin with `@` inside a `/** ... */` comment.

Interview questions

What is Javadoc, and why are tags used?

Javadoc is Java's documentation mechanism for generating API documentation from specially formatted comments. A Javadoc comment starts with `/**` and can contain normal descriptive text and structured tags. Tags such as `@param` and `@return` make common API information explicit and machine-readable. This helps developers understand how to use classes and methods without reading their implementations.

When should you use `@param` and `@return`?

Use `@param` to describe each parameter that a documented method or constructor accepts. The parameter name in the tag should correspond to an actual parameter in the declaration. Use `@return` to explain the value produced by a method that returns a value. A `void` method normally has no return value to document, so `@return` is not appropriate.

What is the purpose of `@throws`?

`@throws` documents an exception that callers should know a method can throw. It normally identifies the exception type followed by a description of the condition that causes it. This gives API users useful information about failure behavior before they inspect the implementation. The documentation should reflect the method's actual behavior and remain consistent with its contract.

What does `@see` do?

`@see` adds a reference to another related class, method, field, or external resource in Javadoc. It is useful when understanding one API element requires consulting another element. For example, documentation for a method can use `@see` to point readers to a related method or class. It improves navigation without duplicating the related documentation.

What is the difference between `@throws`, `throws`, and `throw`?

`@throws` is documentation metadata that explains an exception a method may produce. `throws` is part of a method declaration and specifies checked exceptions that the method can propagate to its caller. `throw` is an executable Java statement that actually throws a particular exception object. They describe or implement related behavior at three different levels: documentation, declaration, and execution.