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
). 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. /** * 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; } }