Class JavadocUtils


  • public final class JavadocUtils
    extends java.lang.Object
    Contains utility methods for working with Javadoc.
    • Field Detail

      • TOKEN_NAME_TO_VALUE

        private static final com.google.common.collect.ImmutableMap<java.lang.String,​java.lang.Integer> TOKEN_NAME_TO_VALUE
        Maps from a token name to value.
      • TOKEN_VALUE_TO_NAME

        private static final java.lang.String[] TOKEN_VALUE_TO_NAME
        Maps from a token value to name.
      • UNKNOWN_JAVADOC_TOKEN_ID_EXCEPTION_MESSAGE

        private static final java.lang.String UNKNOWN_JAVADOC_TOKEN_ID_EXCEPTION_MESSAGE
        Exception message for unknown JavaDoc token id.
        See Also:
        Constant Field Values
      • COMMENT_PATTERN

        private static final java.util.regex.Pattern COMMENT_PATTERN
        Comment pattern.
      • BLOCK_TAG_PATTERN_FIRST_LINE

        private static final java.util.regex.Pattern BLOCK_TAG_PATTERN_FIRST_LINE
        Block tag pattern for a first line.
      • BLOCK_TAG_PATTERN

        private static final java.util.regex.Pattern BLOCK_TAG_PATTERN
        Block tag pattern.
      • INLINE_TAG_PATTERN

        private static final java.util.regex.Pattern INLINE_TAG_PATTERN
        Inline tag pattern.
      • NEWLINE

        private static final java.util.regex.Pattern NEWLINE
        Newline pattern.
      • RETURN

        private static final java.util.regex.Pattern RETURN
        Return pattern.
      • TAB

        private static final java.util.regex.Pattern TAB
        Tab pattern.
    • Constructor Detail

      • JavadocUtils

        private JavadocUtils()
        Prevent instantiation.
    • Method Detail

      • getJavadocTags

        public static JavadocTags getJavadocTags​(TextBlock textBlock,
                                                 JavadocUtils.JavadocTagType tagType)
        Gets validTags from a given piece of Javadoc.
        Parameters:
        textBlock - the Javadoc comment to process.
        tagType - the type of validTags we're interested in
        Returns:
        all standalone validTags from the given javadoc.
      • getBlockTagPattern

        private static java.util.regex.Pattern getBlockTagPattern​(int lineNumber)
        Get a block tag pattern depending on a line number of a javadoc.
        Parameters:
        lineNumber - the line number.
        Returns:
        a block tag pattern.
      • lookForInlineTags

        private static void lookForInlineTags​(TextBlock comment,
                                              int lineNumber,
                                              java.util.List<JavadocTag> validTags,
                                              java.util.List<InvalidJavadocTag> invalidTags)
        Looks for inline tags in comment and adds them to the proper tags collection.
        Parameters:
        comment - comment text block
        lineNumber - line number in the comment
        validTags - collection of valid tags
        invalidTags - collection of invalid tags
      • isJavadocComment

        public static boolean isJavadocComment​(java.lang.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

        private static java.lang.String getBlockCommentContent​(DetailAST blockCommentBegin)
        Gets content of block comment.
        Parameters:
        blockCommentBegin - block comment AST.
        Returns:
        content of block comment.
      • getJavadocCommentContent

        public static java.lang.String getJavadocCommentContent​(DetailAST javadocCommentBegin)
        Get content of Javadoc comment.
        Parameters:
        javadocCommentBegin - Javadoc comment AST
        Returns:
        content of Javadoc comment.
      • 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
      • getFirstChild

        public static DetailNode getFirstChild​(DetailNode node)
        Gets first child node of specified node.
        Parameters:
        node - DetailNode
        Returns:
        first child
      • containsInBranch

        public static boolean containsInBranch​(DetailNode node,
                                               int type)
        Checks whether node contains any node of specified type among children on any deep level.
        Parameters:
        node - DetailNode
        type - token type
        Returns:
        true if node contains any node of type type among children on any deep level.
      • getNextSibling

        public static DetailNode getNextSibling​(DetailNode node)
        Gets next sibling of specified node.
        Parameters:
        node - DetailNode
        Returns:
        next sibling.
      • 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.
      • getPreviousSibling

        public static DetailNode getPreviousSibling​(DetailNode node)
        Gets previous sibling of specified node.
        Parameters:
        node - DetailNode
        Returns:
        previous sibling
      • getTokenName

        public static java.lang.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
      • getTokenId

        public static int getTokenId​(java.lang.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
      • getTagName

        public static java.lang.String getTagName​(DetailNode javadocTagSection)
        Gets tag name from javadocTagSection.
        Parameters:
        javadocTagSection - to get tag name from.
        Returns:
        name, of the javadocTagSection's tag.
      • escapeAllControlChars

        public static java.lang.String escapeAllControlChars​(java.lang.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, or field declarations -- see the class example, method example, and field example. Documentation comments placed in the body of a method are ignored. Only one documentation comment per declaration statement is recognized by the Javadoc tool."
        Parameters:
        blockComment - Block comment AST
        Returns:
        true if Javadoc is in right place