Package com.puppycrawl.tools.checkstyle.utils

Class JavadocUtil

java.lang.Object
com.puppycrawl.tools.checkstyle.utils.JavadocUtil
public final class JavadocUtil extends Object
Contains utility methods for working with Javadoc.

  • Field Details

  • Constructor Details

    • JavadocUtil

      private JavadocUtil()
      Prevent instantiation.

  • Method Details

    • isJavadocComment

      public static boolean isJavadocComment(String commentContent)
      Checks that commentContent starts with '*' javadoc comment identifier.
      Parameters:
      commentContent - content of block comment
      Returns:
      true if commentContent starts with '*' javadoc comment identifier.

    • isJavadocComment

      public static boolean isJavadocComment(DetailAST blockCommentBegin)
      Checks block comment content starts with '*' javadoc comment identifier.
      Parameters:
      blockCommentBegin - block comment AST
      Returns:
      true if block comment content starts with '*' javadoc comment identifier.

    • getBlockCommentContent

      public static String getBlockCommentContent(DetailAST blockCommentBegin)
      Gets content of block comment.
      Parameters:
      blockCommentBegin - block comment AST.
      Returns:
      content of block comment.

    • getJavadocCommentContent

      public static String getJavadocCommentContent(DetailAST javadocCommentBegin)
      Get content of Javadoc comment.
      Parameters:
      javadocCommentBegin - Javadoc comment AST
      Returns:
      content of Javadoc comment.

    • getAttachedJavadocComment

      @Nullable public static DetailAST getAttachedJavadocComment(DetailAST ast)
      Returns the Javadoc block comment attached to the given declaration AST node.
      Parameters:
      ast - the declaration AST node
      Returns:
      the attached Javadoc block comment, or null if none is found

    • getAttachedJavadocCommentForPackage

      @Nullable public static DetailAST getAttachedJavadocCommentForPackage(DetailAST ast)
      Returns the Javadoc block comment attached to the given package AST node. Because of parser bug parser can place javadoc comment either as previous sibling of package definition or (if there is annotation between package def and javadoc) inside package definition tree. So we should look for javadoc in both places.
      Parameters:
      ast - the package declaration AST node
      Returns:
      the attached Javadoc block comment, or null if none is found

    • findJavadocComment

      @Nullable private static DetailAST findJavadocComment(DetailAST ast)
      Finds the first Javadoc block comment under the given AST node.
      Parameters:
      ast - the AST node to search
      Returns:
      the Javadoc block comment, or null if none is found

    • findFirstToken

      public static DetailNode findFirstToken(DetailNode detailNode, int type)
      Returns the first child token that has a specified type.
      Parameters:
      detailNode - Javadoc AST node
      type - the token type to match
      Returns:
      the matching token, or null if no match

    • getAllNodesOfType

      public static List<DetailNode> getAllNodesOfType(DetailNode detailNode, int type)
      Returns all child tokens that have a specified type.
      Parameters:
      detailNode - Javadoc AST node
      type - the token type to match
      Returns:
      the matching tokens, or an empty list if no match

    • isTag

      public static boolean isTag(DetailNode ast, String expectedTagName)
      Checks whether the given AST node is an HTML element with the specified tag name. This method ignore void elements.
      Parameters:
      ast - the AST node to check (must be of type JavadocCommentsTokenTypes.HTML_ELEMENT)
      expectedTagName - the tag name to match (case-insensitive)
      Returns:
      true if the node has the given tag name, false otherwise

    • getNextSibling

      public static DetailNode getNextSibling(DetailNode node, int tokenType)
      Gets next sibling of specified node with the specified type.
      Parameters:
      node - DetailNode
      tokenType - javadoc token type
      Returns:
      next sibling.

    • getTokenName

      public static String getTokenName(int id)
      Returns the name of a token for a given ID.
      Parameters:
      id - the ID of the token name to get
      Returns:
      a token name
      Throws:
      IllegalArgumentException - if an unknown token ID was specified.

    • getTokenId

      public static int getTokenId(String name)
      Returns the ID of a token for a given name.
      Parameters:
      name - the name of the token ID to get
      Returns:
      a token ID
      Throws:
      IllegalArgumentException - if an unknown token name was specified.

    • getTagName

      public static String getTagName(DetailNode javadocTagSection)
      Extracts the tag name from the given Javadoc tag section.
      Parameters:
      javadocTagSection - the node representing a Javadoc tag section. This node must be of type JavadocCommentsTokenTypes.JAVADOC_BLOCK_TAG or JavadocCommentsTokenTypes.JAVADOC_INLINE_TAG.
      Returns:
      the tag name (e.g., "param", "return", "link")

    • escapeAllControlChars

      public static String escapeAllControlChars(String text)
      Replace all control chars with escaped symbols.
      Parameters:
      text - the String to process.
      Returns:
      the processed String with all control chars escaped.

    • isCorrectJavadocPosition

      public static boolean isCorrectJavadocPosition(DetailAST blockComment)
      Checks Javadoc comment it's in right place.

      From Javadoc util documentation: "Placement of comments - Documentation comments are recognized only when placed immediately before class, interface, constructor, method, field or annotation field declarations -- see the class example, method example, and field example. Documentation comments placed in the body of a method are ignored."

      If there are many documentation comments per declaration statement, only the last one will be recognized.

      Parameters:
      blockComment - Block comment AST
      Returns:
      true if Javadoc is in right place
      See Also: