org.sonar.l10n.java.rules.java.S1176.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of sonar-java-plugin Show documentation
Code Analyzer for Java
There is a newer version: 8.6.0.37351
A good API documentation is a key factor in the usability and success of a software API. It ensures that developers can effectively use, maintain,
and collaborate on the API.
Why is this an issue?
Undocumented APIs pose significant challenges in software development for several reasons:

   Lack of Clarity: developers struggling to understand how to use the API correctly. This can lead to misuse and unexpected
  results. 
   Increased Development Time: developers spending extra time reading and understanding the source code, which slows down the
  development process. 
   Error Prone: developers are more likely to make mistakes that lead to bugs or system crashes when the intent or the error
  handling of an API is not clear. 
   Difficult Maintenance and Updates: developers may not understand the existing functionality well enough to add new features
  without breaking the existing ones. 
   Poor Collaboration: collaboration, when there is lack of documentation, leads to confusion and inconsistencies. 

It is recommended to document the API using JavaDoc to clarify what is the contract of the API. This is especially important for
public APIs, as they are used by other developers.
Exceptions
The following public methods and constructors are not taken into account by this rule:

   Getters and setters. 
   Methods overriding another method (usually annotated with @Override). 
   Empty constructors. 
   Static constants. 

How to fix 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 should be documented with @throws 
   @return present and documented when method return type is not void. 
   Placeholders like "TODO", "FIXME", "…" should be avoided. 

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. 

Code examples
Noncompliant code example
/**
  * This is a Javadoc comment
  */
public class MyClass<T> implements Runnable {   // Noncompliant - missing '@param <T>'

  public static final int 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 int 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;
  }
}

Resources
Documentation

   Oracle - JavaDoc 

Articles & blog posts

   Technical Writer HQ - How to write API
  documentation 
   FreeCodeCamp - How to write API documentation like a
  pro