GitHub Twitter Stackoverflow GoogleGroups JProfiler

PreferCodeOrSnippetJavadocInlineTag

Since Checkstyle 14.1.0

On This Page

Description

Checks that Javadoc inline tags {@code ...} and {@snippet ...} are preferred over HTML tags <code> and <pre>.

This check enforces using either {@code ...} or {@snippet ...} inline tags instead of single-line <code> and <pre> HTML tags, and using {@snippet ...} inline tags instead of multi-line <code> and <pre> HTML tags.

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

To suppress violation for snippet inline tag: 


    <module name="SuppressionSingleFilter">
      <property name="checks" value="PreferCodeOrSnippetJavadocInlineTag"/>
      <property name="files" value="file-name"/>
      <property name="message" value="Use snippet inline tag instead of.*"/>
    </module>
Not Flagged :
  • Tags which have unbalanced curly braces
  • Tags which have content that starts with star.
  • Tags which are inside other 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 14.1.0

Examples

To configure the check: 


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

Example1: 


public class Example1 {
  // violation 2 lines below "Use code or snippet inline tags instead of 'pre' tag."
  /**
   * <pre> This is a single line pre.</pre>
   */
  public void badMethodPre() {
  }

  /**
   * {@code This is a single line pre.}
   * {@snippet :
   *     This is a single line pre.
   * }
   */
  public void goodMethodPre() {
  }

  // violation 2 lines below 'Use code or snippet inline tags instead of 'code' tag.'
  /**
   * <code> int x = 10; </code>
   * <code>This is a left curly }</code> // ok because of unbalanced braces
   */
  public void badMethodCode() {
  }

  /**
   * {@code int x = 10;}
   * {@snippet :
   *      int x = 10;
   * }
   */
  public void goodMethodCode() {
  }

  // violation 2 lines below "Use snippet inline tag instead of 'pre' tag."
  /**
   * <pre>
   *      <code>Nested code in pre tag.</code>
   * </pre>
   * <pre>{@code  // ok the inside text started with '*'
   * /**
   *   * This is a javadoc inside javadoc start with star.
   *   * /
   * }</pre>
   */
  public void badMethod1() {
  }

}

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

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

Parent Module

TreeWalker