A documentation comment must start with /**. A regular comment that contains Javadoc tags or HTML documentation tags, and that sits immediately above a declaration, is ignored by the Javadoc tool, so the following declaration stays undocumented.

Why is this an issue?

The Javadoc tool recognizes documentation comments that start with /** and that are placed immediately before a class, interface, constructor, method, field, or enum constant. A comment that starts with /* or // in that position is ordinary commentary.

When such a comment contains Javadoc tags such as @param, @return, or {@link}, or HTML documentation tags such as </code> or </em>, it is almost always intended to be Javadoc. Because it is not a documentation comment, those tags never attach to the following declaration. Readers and generated API docs then miss the contract that the author already wrote.

Start the comment with /** so the tags document the following declaration.

Exceptions

This rule does not raise an issue when:

Code examples

Noncompliant code example

public class MathUtils {
  /* // Noncompliant: not a documentation comment, so these tags are ignored
   * Computes the factorial of a positive integer.
   * @param n the number to compute factorial for
   * @return the factorial of n
   */
  public long factorial(int n) {
    return (n <= 1) ? 1 : n * factorial(n - 1);
  }
}

Compliant solution

public class MathUtils {
  /**
   * Computes the factorial of a positive integer.
   * @param n the number to compute factorial for
   * @return the factorial of n
   */
  public long factorial(int n) {
    return (n <= 1) ? 1 : n * factorial(n - 1);
  }
}

Noncompliant code example

public class Names {
  /* Returns the display name as <code>String</code>. */ // Noncompliant: HTML documentation tags in a regular block comment
  public String displayName() {
    return name;
  }
}

Compliant solution

public class Names {
  /** Returns the display name as <code>String</code>. */
  public String displayName() {
    return name;
  }
}

Noncompliant code example

interface Repository {
  // Loads the entity. {@link Entity} */ // Noncompliant: line comment is not started with /**
  Entity load(String id);
}

Compliant solution

interface Repository {
  /** Loads the entity. {@link Entity} */
  Entity load(String id);
}

Resources

Documentation

Related rules