GitHub Twitter Stackoverflow GoogleGroups JProfiler

JavadocLinkFirstOccurrence

Since Checkstyle 14.1.0

On This Page

Description

Checks that in Javadoc comments, each API name is linked with {@link} or {@linkplain} only on its first occurrence. Subsequent links to the same API name in the same comment are flagged.

Rationale: From the Documentation Comments style guide, links call attention to themselves by their color and underline in HTML, and by their length in source code doc comments. Linking the same name multiple times is redundant.

Two links are considered to reference the same API name if they resolve to the same canonical name. Simple names are resolved through explicit imports, types declared in the current file, star imports and the java.lang package. Names containing dots are resolved through imports of their outermost segment; otherwise they are compared as written.

Properties

name description type default value since
violateExecutionOnNonTightHtml Control when to print violations if the Javadoc being examined by this check violates the tight html rules defined at Tight-HTML Rules. boolean false 14.1.0

Examples

To configure the check: 


<module name="Checker">
  <module name="TreeWalker">
    <module name="JavadocLinkFirstOccurrence"/>
  </module>
</module>

Example:


class Example1 {

  /**
   * Uses a {@link String}.
   * The String is returned.
   */
  public String valid1() { return ""; }

  // violation 3 lines below 'String' should be linked only on its first occurrence
  /**
   * Uses a {@link String}.
   * The {@link String} is returned.
   */
  public String invalid1() { return ""; }

  /**
   * Uses a {@link String} and an {@link Object}.
   * The String is converted to an Object.
   */
  public Object valid2(String s) { return s; }

  // 2 violations 5 lines below:
  // ''String' should be linked only on its first occurrence'
  // ''Object' should be linked only on its first occurrence'
  /**
   * Uses a {@link String} and an {@link Object}.
   * The {@link String} is converted to an {@link Object}.
   */
  public Object invalid2(String s) { return s; }

  // violation 3 lines below 'String' should be linked only on its first occurrence
  /**
   * Uses a {@linkplain String}.
   * The {@linkplain String} is returned.
   */
  public String invalid3() { return ""; }

  /**
   * Uses {@link #method()} and {@link String}.
   */
  public void valid3() { }
}

Example of Usage

Violation Messages

All messages can be customized if the default message doesn't suit you. Please see the documentation to learn how to.

Fully Qualified Name

com.puppycrawl.tools.checkstyle.checks.javadoc.JavadocLinkFirstOccurrenceCheck

Use this fully qualified class name in configuration when an exact class reference is required.

Parent Module

TreeWalker