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

Go to download

Show more of this group Show more artifacts with this name
Show all versions of java-checks Show documentation

There is a newer version: 8.6.0.37351

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.
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.

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

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

  /**
    *  {@inheritDoc}
    */
  public int doSomething(int value) {
    return value;
  }
}