GitHub Twitter Stackoverflow GoogleGroups JProfiler

PreferLiteralJavadocInlineTag

Since Checkstyle 13.10.0

Description

Checks that Javadoc inline tags are preferred over HTML equivalents.

Per OpenJDK Style Guidelines v6 Javadoc inline tags should be preferred over their HTML equivalents.

Violations:

  • {@literal <} or {@code <} over &lt;
  • {@literal >} or {@code >} over &gt;

Not flagged:

  • Content inside <pre> and <code> blocks (code examples)
  • Content inside {@code}, {@literal}, {@snippet} inline tags

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 13.10.0

Examples

To configure the check: 


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

Example:


public class Example1 {

  // 2 violations 4 lines below:
  //  'Prefer literal or code javadoc inline tag over '&lt;'.'
  //  'Prefer literal or code javadoc inline tag over '&gt;'.'
  /**
    * Type parameter is &lt;E&gt; here.
    */
  public void badMethod() {
  }

  /**
    * Type parameter is {@literal <E>} here.
    */
  public void goodMethod() {
  }

  // violation 4 lines below """Prefer literal or code javadoc
  // inline tag over '&gt;'."""
  /**
   * <p>
   *    &gt; is the greater than sign.
   * </p>
   */
  public void gtEntityAtStart() {
  }

  /**
   * Content inside pre blocks is allowed:
   * <pre>
   * <code>sample</code>;
   * &lt;a href="#method"&gt;link&lt;/a&gt;
   * </pre>
   */
  public void insidePreBlock() { }

  /**
   * Content inside inline tags is allowed:
   * Literal: {@literal <code>&lt;T&gt;</code>}
   * {@snippet :
   *    &lt;T&gt;
   * }
   */
  public void insideInlineTags() { }
}

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.PreferLiteralJavadocInlineTagCheck

Parent Module

TreeWalker