Package com.puppycrawl.tools.checkstyle.checks.javadoc

Class PreferCodeOrSnippetJavadocInlineTagCheck

java.lang.Object
com.puppycrawl.tools.checkstyle.AbstractAutomaticBean
com.puppycrawl.tools.checkstyle.api.AbstractViolationReporter
com.puppycrawl.tools.checkstyle.api.AbstractCheck
com.puppycrawl.tools.checkstyle.checks.javadoc.AbstractJavadocCheck
com.puppycrawl.tools.checkstyle.checks.javadoc.PreferCodeOrSnippetJavadocInlineTagCheck
All Implemented Interfaces:
Configurable, Contextualizable
public class PreferCodeOrSnippetJavadocInlineTagCheck extends AbstractJavadocCheck
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
Since:
14.1.0

  • Field Details

  • Constructor Details

  • Method Details

    • getRequiredJavadocTokens

      public int[] getRequiredJavadocTokens()
      Description copied from class: AbstractJavadocCheck
      The javadoc tokens that this check must be registered for.
      Overrides:
      getRequiredJavadocTokens in class AbstractJavadocCheck
      Returns:
      the javadoc token set this must be registered for.
      See Also:

    • getDefaultJavadocTokens

      public int[] getDefaultJavadocTokens()
      Description copied from class: AbstractJavadocCheck
      Returns the default javadoc token types a check is interested in.
      Specified by:
      getDefaultJavadocTokens in class AbstractJavadocCheck
      Returns:
      the default javadoc token types
      See Also:

    • visitJavadocToken

      public void visitJavadocToken(DetailNode node)
      Description copied from class: AbstractJavadocCheck
      Called to process a Javadoc token.
      Specified by:
      visitJavadocToken in class AbstractJavadocCheck
      Parameters:
      node - the token to process

    • isCodeOrPreTag

      private static boolean isCodeOrPreTag(DetailNode node)
      Checks if the tag is code or pre tag.
      Parameters:
      node - the node to check
      Returns:
      true if the tag is code or pre tag, false otherwise

    • isNested

      private static boolean isNested(DetailNode node)
      Checks if the tag is nested inside any other code or pre tag.
      Parameters:
      node - the node to check
      Returns:
      true if the tag is nested, false otherwise

    • isConvertableInInlineTag

      public static boolean isConvertableInInlineTag(Iterable<DetailNode> listOfTextNodes)
      Checks if the tag is convertable in inline tag.
      Parameters:
      listOfTextNodes - the list of text nodes to check.
      Returns:
      true if the tag is convertable in inline tag, false otherwise.

    • containsBalancedBraces

      public static boolean containsBalancedBraces(Iterable<DetailNode> listOfTextNodes)
      Checks if the text list contains balanced braces.
      Parameters:
      listOfTextNodes - the list of text nodes to check
      Returns:
      true if the text list contains balanced braces, false otherwise

    • isStartWithStar

      private static boolean isStartWithStar(Iterable<DetailNode> listOfTextNodes)
      Checks if the first element of the text list starts with a star.
      Parameters:
      listOfTextNodes - the list of text nodes to check
      Returns:
      true if the first element of the text list does not start with a star, false otherwise

    • collectTextNodes

      public static List<DetailNode> collectTextNodes(DetailNode node)
      Collects all text nodes contained within the specified node, including text nested inside HTML elements and inline tags.
      Parameters:
      node - the root DetailNode to extract text nodes from
      Returns:
      a list of text DetailNode instances

    • getTextNodesFromInlineTags

      private static List<DetailNode> getTextNodesFromInlineTags(Iterable<DetailNode> inlineTags)
      Extracts text nodes from child nodes of the provided list of inline tags.
      Parameters:
      inlineTags - the list of inline tag DetailNodes
      Returns:
      a list of text DetailNode instances found inside the inline tags

    • isSingleLineTag

      private static boolean isSingleLineTag(DetailNode node)
      Checks if the tag is single-line.
      Parameters:
      node - the node to check
      Returns:
      true if the tag is single-line, false otherwise

    • isCompleteTag

      private static boolean isCompleteTag(DetailNode node)
      Checks if the tag is complete.
      Parameters:
      node - the node to check
      Returns:
      true if the tag is complete, false otherwise

    • getHtmlTagName

      @Nullable private static String getHtmlTagName(DetailNode htmlElement)
      Gets the tag name from an HTML_ELEMENT node.
      Parameters:
      htmlElement - the HTML_ELEMENT node
      Returns:
      the tag name (e.g., "code", "pre")