GitHub Twitter Stackoverflow GoogleGroups JProfiler

PreferLiteralJavadocInlineTag

Since Checkstyle 13.11.0

On This Page

Description

Checks that Javadoc inline tags are preferred over escaping entities. According to OpenJDK Style Guidelines v6 Javadoc inline tags should be preferred over their HTML equivalents. Entities that are flagged by the check are:
  • <
  • >
  • &
  • "
  • '

Reason of only these entities are flagged is given here : Predefined Entities

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

Examples

To configure the check: 


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

Example:


public class Example1 {

  // 5 violations 7 lines below:
  //  'Prefer literal or code javadoc inline tag over '&lt;'.'
  //  'Prefer literal or code javadoc inline tag over '&gt;'.'
  //  'Prefer literal or code javadoc inline tag over '&amp;'.'
  //  'Prefer literal or code javadoc inline tag over '&quot;'.'
  //  'Prefer literal or code javadoc inline tag over '&apos;'.'
  /**
   * Entities are : &lt;, &gt;, &amp;, &quot;, &apos;.
   */
  public void badMethod() {
  }

  /**
   * Entities are : {@literal <}, {@literal >},
   * {@literal &}, {@literal "}, {@literal '}.
   */
  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