rspec/rules/S1176/java/rule.adoc

include::../introduction.adoc[]

== Why is this an issue?

include::../why-is-this-an-issue.adoc[]

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

[source,java,diff-id=1,diff-type=noncompliant]
----
/**
  * 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

[source,java,diff-id=1,diff-type=compliant]
----
/**
  * 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 - https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html[JavaDoc]

=== Articles & blog posts

include::../articles-and-blog-posts.adoc[]


ifdef::env-github,rspecator-view[]

'''
== Implementation Specification
(visible only on this page)

=== Message

Document this public [class|interface|method|constructor|field|enum|annotation].

Document the parameter(s): {...}

Document this method return value.


=== Parameters

.forClasses
****

----
**/api/**
----

Pattern of classes which should adhere to this constraint. Ex : **/api/**
****


'''
== Comments And Links
(visible only on this page)

include::../comments-and-links.adoc[]

endif::env-github,rspecator-view[]