PreferJavadocInlineTags

Since Checkstyle 13.9.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 (HTML tags that should be replaced):

{@code ...} over <code>...</code>
{@link ...} over <a href="#..."> for internal references
{@literal <} over <
{@literal >} over >
{@snippet ...} over <pre>...</pre>

Not flagged:

Block-level HTML tags with no Javadoc equivalent: <p>, <div>, <ul>, <ol>, <li>, <table>, <blockquote>, etc.
Content inside <pre> blocks (code examples)
Content inside {@code}, {@literal} and {@snippet} inline tags

Properties

name	description	type	default value	since
jdkVersion	Set the JDK version that you are using. Old JDK version numbering is supported (e.g. 1.8 for Java 8) as well as just the major JDK version alone (e.g. 8) is supported. This property only considers features from officially released Java versions as supported. Features introduced in preview releases are not considered supported until they are included in a non-preview release.	int	`25`	13.9.0
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.9.0

Examples

To configure the check:


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

Example:


public class Example1 {
  // violation 2 lines below 'Prefer Javadoc inline tag '{@code ...}''
  /**
   * Returns <code>true</code> if valid.
   */
  public boolean isValid() { return true; }

  // violation 2 lines below 'Prefer Javadoc inline tag '{@link ...}''
  /**
   * See <a href="#validate">validate</a>.
   */
  public void method() { }

  // 2 violations 4 lines below:
  //  'Prefer Javadoc inline tag '{@literal <}' over '&lt;'.'
  //  'Prefer Javadoc inline tag '{@literal >}' over '&gt;'.'
  /**
   * Use &lt;T&gt; for generic types.
   */
  public void generics() { }

  /**
   * Correct: Returns {@code true}.
   */
  public void correctUsage() { }

  /**
   * External links are allowed: <a href="https://example.com">link</a>.
   */
  public void externalLink() { }
  // violation 3 lines below 'Prefer Javadoc inline tag '{@snippet ...}''
  /**
   * 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>}
   */
  public void insideInlineTags() { }
}

To configure the check if you are using JDK 17:


<module name="Checker">
  <module name="TreeWalker">
    <module name="PreferJavadocInlineTags">
       <property name="jdkVersion" value="17"/>
    </module>
  </module>
</module>

Example:


public class Example2 {
  // violation 2 lines below 'Prefer Javadoc inline tag '{@code ...}''
  /**
   * Returns <code>true</code> if valid.
   */
  public boolean isValid() { return true; }

  // violation 2 lines below 'Prefer Javadoc inline tag '{@link ...}''
  /**
   * See <a href="#validate">validate</a>.
   */
  public void method() { }

  // 2 violations 4 lines below:
  //  'Prefer Javadoc inline tag '{@literal <}' over '&lt;'.'
  //  'Prefer Javadoc inline tag '{@literal >}' over '&gt;'.'
  /**
   * Use &lt;T&gt; for generic types.
   */
  public void generics() { }

  /**
   * Correct: Returns {@code true}.
   */
  public void correctUsage() { }

  /**
   * External links are allowed: <a href="https://example.com">link</a>.
   */
  public void externalLink() { }

  /**
   * 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>}
   */
  public void insideInlineTags() { }
}

Example of Usage

Checkstyle Style

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

Parent Module

TreeWalker