Class JavadocDetailNodeParser

java.lang.Object
com.puppycrawl.tools.checkstyle.JavadocDetailNodeParser

public class JavadocDetailNodeParser extends Object
Used for parsing Javadoc comment as DetailNode tree.
  • Field Details

    • MSG_JAVADOC_MISSED_HTML_CLOSE

      public static final String MSG_JAVADOC_MISSED_HTML_CLOSE
      Message key of error message. Missed close HTML tag breaks structure of parse tree, so parser stops parsing and generates such error message. This case is special because parser prints error like "no viable alternative at input 'b \n *\n'" and it is not clear that error is about missed close HTML tag.
      See Also:
    • MSG_JAVADOC_WRONG_SINGLETON_TAG

      public static final String MSG_JAVADOC_WRONG_SINGLETON_TAG
      Message key of error message.
      See Also:
    • MSG_JAVADOC_PARSE_RULE_ERROR

      public static final String MSG_JAVADOC_PARSE_RULE_ERROR
      Parse error while rule recognition.
      See Also:
    • MSG_UNCLOSED_HTML_TAG

      public static final String MSG_UNCLOSED_HTML_TAG
      Message property key for the Unclosed HTML message.
      See Also:
    • JAVADOC_START

      private static final String JAVADOC_START
      Symbols with which javadoc starts.
      See Also:
    • blockCommentLineNumber

      private int blockCommentLineNumber
      Line number of the Block comment AST that is being parsed.
  • Constructor Details

    • JavadocDetailNodeParser

      public JavadocDetailNodeParser()
  • Method Details

    • parseJavadocAsDetailNode

      public JavadocDetailNodeParser.ParseStatus parseJavadocAsDetailNode(DetailAST javadocCommentAst)
      Parses Javadoc comment as DetailNode tree.
      Parameters:
      javadocCommentAst - DetailAST of Javadoc comment
      Returns:
      DetailNode tree of Javadoc comment
    • createJavadocParser

      private static JavadocParser createJavadocParser(String blockComment, JavadocDetailNodeParser.DescriptiveErrorListener errorListener)
      Parses block comment content as javadoc comment.
      Parameters:
      blockComment - block comment content.
      errorListener - custom error listener
      Returns:
      parse tree
    • convertParseTreeToDetailNode

      private DetailNode convertParseTreeToDetailNode(org.antlr.v4.runtime.tree.ParseTree parseTreeNode)
      Converts ParseTree (that is generated by ANTLRv4) to DetailNode tree.
      Parameters:
      parseTreeNode - root node of ParseTree
      Returns:
      root of DetailNode tree
    • insertChildrenNodes

      private void insertChildrenNodes(JavadocNodeImpl[] nodes, org.antlr.v4.runtime.tree.ParseTree parseTreeParent)
      Creates child nodes for each node from 'nodes' array.
      Parameters:
      nodes - array of JavadocNodeImpl nodes
      parseTreeParent - original ParseTree parent node
    • createChildrenNodes

      private JavadocNodeImpl[] createChildrenNodes(JavadocNodeImpl parentJavadocNode, org.antlr.v4.runtime.tree.ParseTree parseTreeNode)
      Creates children Javadoc nodes base on ParseTree node's children.
      Parameters:
      parentJavadocNode - node that will be parent for created children
      parseTreeNode - original ParseTree node
      Returns:
      array of Javadoc nodes
    • createRootJavadocNode

      private JavadocNodeImpl createRootJavadocNode(org.antlr.v4.runtime.tree.ParseTree parseTreeNode)
      Creates root JavadocNodeImpl node base on ParseTree root node.
      Parameters:
      parseTreeNode - ParseTree root node
      Returns:
      root Javadoc node
    • createJavadocNode

      private JavadocNodeImpl createJavadocNode(org.antlr.v4.runtime.tree.ParseTree parseTree, DetailNode parent, int index)
      Creates JavadocNodeImpl node on base of ParseTree node.
      Parameters:
      parseTree - ParseTree node
      parent - DetailNode that will be parent of new node
      index - child index that has new node
      Returns:
      JavadocNodeImpl node on base of ParseTree node.
    • adjustFirstLineToJavadocIndent

      private void adjustFirstLineToJavadocIndent(DetailNode tree, int javadocColumnNumber)
      Adjust first line nodes to javadoc indent.
      Parameters:
      tree - DetailNode tree root
      javadocColumnNumber - javadoc indent
    • getLine

      private static int getLine(org.antlr.v4.runtime.tree.ParseTree tree)
      Gets line number from ParseTree node.
      Parameters:
      tree - ParseTree node
      Returns:
      line number
    • getColumn

      private static int getColumn(org.antlr.v4.runtime.tree.ParseTree tree)
      Gets column number from ParseTree node.
      Parameters:
      tree - ParseTree node
      Returns:
      column number
    • getNextSibling

      private static org.antlr.v4.runtime.tree.ParseTree getNextSibling(org.antlr.v4.runtime.tree.ParseTree node)
      Gets next sibling of ParseTree node.
      Parameters:
      node - ParseTree node
      Returns:
      next sibling of ParseTree node.
    • getTokenType

      private static int getTokenType(org.antlr.v4.runtime.tree.ParseTree node)
      Gets token type of ParseTree node from JavadocTokenTypes class.
      Parameters:
      node - ParseTree node.
      Returns:
      token type from JavadocTokenTypes
    • getFormattedNodeClassNameWithoutContext

      private static String getFormattedNodeClassNameWithoutContext(org.antlr.v4.runtime.tree.ParseTree node)
      Gets class name of ParseTree node and removes 'Context' postfix at the end and formats it.
      Parameters:
      node - ParseTree node whose class name is to be formatted and returned
      Returns:
      uppercased class name without the word 'Context' and with appropriately inserted underscores
    • getNodeClassNameWithoutContext

      private static String getNodeClassNameWithoutContext(org.antlr.v4.runtime.tree.ParseTree node)
      Gets class name of ParseTree node and removes 'Context' postfix at the end.
      Parameters:
      node - ParseTree node.
      Returns:
      class name without 'Context'
    • getMissedHtmlTag

      private static org.antlr.v4.runtime.Token getMissedHtmlTag(org.antlr.v4.runtime.RecognitionException exception)
      Method to get the missed HTML tag to generate more informative error message for the user. This method doesn't concern itself with void elements since it is forbidden to close them. Missed HTML tags for the following tags will not generate an error message from ANTLR: <p> <li> <tr> <td> <th> <body> <colgroup> <dd> <dt> <head> <html> <option> <tbody> <thead> <tfoot>
      Parameters:
      exception - NoViableAltException object catched while parsing javadoc
      Returns:
      returns appropriate Token if a HTML close tag is missed; null otherwise
    • getFirstNonTightHtmlTag

      private static org.antlr.v4.runtime.Token getFirstNonTightHtmlTag(JavadocParser javadocParser, int javadocLineOffset)
      This method is used to get the first non-tight HTML tag encountered while parsing javadoc. This shall eventually be reflected by the JavadocDetailNodeParser.ParseStatus object returned by parseJavadocAsDetailNode(DetailAST) method via the instance member JavadocDetailNodeParser.ParseStatus.firstNonTightHtmlTag, and checks not supposed to process non-tight HTML or the ones which are supposed to log violation for non-tight javadocs can utilize that.
      Parameters:
      javadocParser - The ANTLR recognizer instance which has been used to parse the javadoc
      javadocLineOffset - The line number of beginning of the Javadoc comment
      Returns:
      First non-tight HTML tag if one exists; null otherwise
    • convertUpperCamelToUpperUnderscore

      private static String convertUpperCamelToUpperUnderscore(String text)
      Converts the given text from camel case to all upper case with underscores separating each word.
      Parameters:
      text - The string to convert.
      Returns:
      The result of the conversion.