Why is this an issue?

When multiple Javadoc comments (/** */ and /// ///) are placed consecutively above a class, method, or field, only the last one (the one closest to the documented element) will be processed by the Javadoc tool. Any preceding Javadoc comments become "dangling" comments that are ignored by the documentation generator.

This pattern is counter-intuitive and can lead to several problems:

• Important documentation may be accidentally omitted from the generated Javadoc
• Developers may mistakenly believe that all Javadoc comments are being included in the documentation
• The presence of multiple Javadoc blocks creates confusion about which documentation is actually used
• Dangling Javadoc comments may contain outdated or incorrect information that appears to be part of the documentation but is actually ignored

How to fix it

Remove or merge the dangling Javadoc comments, keeping only the Javadoc comment that is immediately adjacent to the documented element.

If the dangling comment contains useful information, merge it into the active Javadoc comment. If the dangling comment is outdated or unnecessary, remove it entirely.

Code examples

Noncompliant code example

/**
 * This is a dangling javadoc comment that will be ignored.
 */
/**
 * This is the actual javadoc that will be used.
 * @param name the name parameter
 */
public void setName(String name) { // Noncompliant - dangling Javadoc comment above
  this.name = name;
}

/**
 * Old documentation that is no longer relevant.
 */
/**
 * Updated documentation for this class.
 */
public class User { // Noncompliant - dangling Javadoc comment above
  private String name;
}

/**
 * This traditional javadoc will be ignored.
 */
/// This markdown javadoc will be used.
/// Represents a customer entity.
public class Customer { // Noncompliant - dangling traditional Javadoc before markdown Javadoc
  private String customerId;
}

Compliant solution

/**
 * Sets the name parameter.
 * @param name the name parameter
 */
public void setName(String name) { // Compliant
  this.name = name;
}

/**
 * Updated documentation for this class.
 */
public class User { // Compliant
  private String name;
}

/// This markdown javadoc will be used.
/// Represents a customer entity.
public class Customer { // Compliant
  private String customerId;
}

Resources

Documentation

• Javadoc Documentation Comment Specification
• How to Write Doc Comments for the Javadoc Tool