org.sonar.l10n.squidjava.rules.squid.UndocumentedApi.html Maven / Gradle / Ivy

Go to download

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 API with Javadoc increases the productivity of the developers consuming it.


The following Javadoc elements are required:

  Parameters, using @param parameterName.
  Method return values, using @return.
  Generic types, using @param <T>.


The following public methods and constructors are not taken into account by this rule:

  Getters and setters.
  Methods with @Override annotation.
  Empty constructors.
  Static constants.


The following code snippet illustrates this rule:

/**
  * This is a Javadoc comment
  */
public class MyClass<T> implements Runnable {    // Non-Compliant - missing '@param <T>'

  public static final DEFAULT_STATUS = 0;        // Compliant - static constant
  private int status;                            // Compliant - not public

  /**
    * This is a Javadoc comment
    */
  public String message;                         // Compliant - well documented

  public MyClass() {                             // Non-Compliant - 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
  }

  /**
    * @param value ...
    */
  public void doSomething(int value) {           // Compliant
  }

  /**
    */
  public int doSomething(int value) {            // Non-Compliant - missing '@param value' and '@return'
    return value;
  }
}