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 ``++@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;
  }
}
----

ifdef::env-github,rspecator-view[]
'''
== Comments And Links
(visible only on this page)

include::../comments-and-links.adoc[]
endif::env-github,rspecator-view[]