Details
-
Type:
Language-Specification
-
Status: Active
-
Resolution: Unresolved
-
Labels:None
-
Impact:Unknown 'null' severity
-
Likelihood:Unknown 'null' severity
-
Legacy Key:UndocumentedApi
Description
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
Examples:
- 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.
Noncompliant Code Example
/** * This is a Javadoc comment */ public class MyClass<T> implements Runnable { // Noncompliant - missing '@param <T>' public static final DEFAULT_STATUS = 0; // Compliant - static constant private int status; // Compliant - not public public String message; // Noncompliant public MyClass() { // Noncompliant - missing documentation this.status = DEFAULT_STATUS; } public void setStatus(int status) { // Compliant - setter this.status = status; } @Override public void run() { // Compliant - has @Override annotation } protected void doSomething() { // Compliant - not public } public void doSomething2(int value) { // Noncompliant } public int doSomething3(int value) { // Noncompliant return value; } }
Compliant Solution
/** * This is a Javadoc comment * @param <T> the parameter of the class */ public class MyClass<T> implements Runnable { public static final DEFAULT_STATUS = 0; private int status; /** * This is a Javadoc comment */ public String message; /** * Class comment... */ public MyClass() { this.status = DEFAULT_STATUS; } public void setStatus(int status) { this.status = status; } @Override public void run() { } protected void doSomething() { } /** * Will do something. * @param value the value to be used */ public void doSomething(int value) { /** * {@inheritDoc} */ public int doSomething(int value) { return value; } }
Attachments
Issue Links
- is related to
-
SONARJAVA-1557 FP on UndocumentedApi: public constructors of non-public classes are not public
-
- Closed
-
