rspec/rules/S1176/java/rule.adoc

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 <code>@param parameterName</code>.
* Thrown exceptions, using <code>@throws exceptionName</code>.
* Method return values, using <code>@return</code>.
* Generic types, using <code>@param &lt;T&gt;</code>.

Furthermore the following guidelines should be followed:
* At least 1 line of description.
* All parameters documented with <code>@param</code>, and names should match.
* All checked exceptions documented with <code>@throws</code>
* <code>@return</code> present and documented when not <code>void</code>.
* 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 <code>@Override</code>).
* Empty constructors.
* Static constants.

== 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;
  }
}
----