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