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.
The following Javadoc elements are required:
@param parameterName
. @return
. @param <T>
. The following public methods and constructors are not taken into account by this rule:
/** * 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; } }
/** * This is a Javadoc comment * @param <T> ... */ 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() { } /** * @param value ... */ public void doSomething(int value) { /** * {@inheritDoc} */ public int doSomething(int value) { return value; } }