Javadoc

Javadoc documents Java APIs directly in source code and can generate navigable HTML reference documentation. It uses specially formatted comments to describe classes, methods, fields, parameters, return values, exceptions, and other API details.

Javadoc comments use the `/** ... */` syntax and are placed immediately before the declaration they document. Unlike ordinary `/* ... */` comments, Javadoc comments are recognized by the Javadoc tool and can be turned into API documentation.

A Javadoc comment normally contains descriptive text followed by tags such as `@param`, `@return`, and `@throws`. For example, a method can document what it does, what each argument means, what it returns, and which exceptions callers should expect.

The Javadoc tool processes source declarations and their Javadoc comments to produce documentation, commonly as HTML. The generated documentation links related classes, methods, fields, and packages so developers can navigate an API without reading its implementation.

Javadoc is particularly useful for public and protected APIs because the documentation travels with the source declaration. Good Javadoc explains the contract and behavior that callers need to understand rather than merely restating the method name or implementation.

Key points

• Use `/** ... */` for Javadoc comments.
• Common tags include `@param`, `@return`, `@throws`, `@see`, and `@since`.
• Javadoc can generate navigable HTML API documentation from Java source.
• Document the API contract and caller-visible behavior, not implementation details.
• Javadoc comments can be attached to classes, interfaces, methods, constructors, and fields.

Interview questions

What makes Javadoc useful for a backend API?

For backend code, Javadoc can make service, repository, utility, and domain APIs easier to understand and reuse. The most valuable documentation describes observable behavior, preconditions, side effects, return values, and relevant exceptions. It should avoid repeating obvious implementation details that can change without affecting callers. Consistent documentation is especially useful when multiple developers consume shared Java libraries or services.

What problems can poor Javadoc cause?

Poor Javadoc can mislead callers when it becomes inconsistent with actual behavior. Documentation that merely repeats method names or implementation mechanics provides little value and can become expensive to maintain. Missing information about parameters, return values, exceptions, or side effects can also cause incorrect API usage. Good Javadoc should therefore describe stable, externally observable behavior and be updated when the API contract changes.

What is Javadoc, and why is it used?

Javadoc is Java's documentation mechanism for describing APIs in source code. Documentation is written with `/** ... */` comments and can be processed into navigable API reference pages. It is useful because the documentation stays close to the declarations it describes. It helps callers understand an API without inspecting its implementation.

What is the difference between `/* ... */` and `/** ... */`?

Both are Java block-comment forms, but they have different purposes. `/** ... */` is the documentation-comment form recognized by Javadoc tooling. It can contain structured tags such as `@param` and `@return`. A regular `/* ... */` comment is simply a source-code comment and is not treated as Javadoc documentation.

What are `@param`, `@return`, and `@throws` used for?

`@param` documents an input parameter and normally names that parameter explicitly. `@return` describes the value returned by a non-void method. `@throws` documents an exception that callers may need to handle or understand. These tags make the method contract easier to consume from generated documentation.