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
{@code ... }
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.