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:
@param parameterName
. @throws exceptionName
. @return
. @param <T>
. Furthermore the following guidelines should be followed:
@param
, and names should match. @throws
@return
present and documented when not void
. The following public methods and constructors are not taken into account by this rule:
@Override
annotation. /** * 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> 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; } }