Java Documentation (Javadoc) Best Practices
- Public and protected members should be documented with Javadoc comments.
- It is encouraged to document package-private and private members as well, especially if they are complex or not self-explanatory.
- The first sentence of the Javadoc comment is the summary description. It should be a concise overview of what the method does and end with a period.
- Use
@param for method parameters. The description starts with a lowercase letter and does not end with a period.
- Use
@return for method return values.
- Use
@throws or @exception to document exceptions thrown by methods.
- Use
@see for references to other types or members.
- Use
{@inheritDoc} to inherit documentation from base classes or interfaces.
- Unless there is major behavior change, in which case you should document the differences.
- Use
@param <T> for type parameters in generic types or methods.
- Use
{@code} for inline code snippets.
- Use
<pre>{@code ... }</pre> for code blocks.
- Use
@since to indicate when the feature was introduced (e.g., version number).
- Use
@version to specify the version of the member.
- Use
@author to specify the author of the code.
- Use
@deprecated to mark a member as deprecated and provide an alternative.