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

Why is this an issue?

Exceptions

How to fix it

Code examples

Noncompliant code example

Compliant solution

Resources

Documentation

Articles & blog posts