Impact:Unknown 'null' severity
Likelihood:Unknown 'null' severity
Try to imagine using the standard Java API (Collections, JDBC, IO, ...) without Javadoc. It would be a nightmare, because Javadoc is the only way to understand of the contract of the API. Documenting an API with Javadoc increases the productivity of the developers consuming it.
On top of a main description for each member of a public API, the following Javadoc elements are required to be described:
- Parameters, using @param parameterName.
- Thrown exceptions, using @throws exceptionName.
- Method return values, using @return.
- Generic types, using @param <T>.
Furthermore the following guidelines should be followed:
- At least 1 line of description.
- All parameters documented with @param, and names should match.
- All checked exceptions documented with @throws
- @return present and documented when not void.
- Placeholders like "TODO", "FIXME", "..." should be avoided.
The following public methods and constructors are not taken into account by this rule:
- Getters and setters.
- Methods overriding another method (usually decorated with @Override).
- Empty constructors.
- Static constants.
For the parameters of the rule, the following rules are applied:
- ? matches a single character
- * matches zero or more characters
- ** matches zero or more packages
- java.internal.InternalClass will match only InternalClass class.
- java.internal.* will match any member of java.internal package.
- java.internal.** same as above, but including sub-packages.