Why is this an issue?
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;
}
}
