com.puppycrawl.tools.checkstyle

Class JavadocDetailNodeParser

java.lang.Object

com.puppycrawl.tools.checkstyle.JavadocDetailNodeParser

public class JavadocDetailNodeParser
extends java.lang.Object

Used for parsing Javadoc comment as DetailNode tree.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	JavadocDetailNodeParser.DescriptiveErrorListener Custom error listener for JavadocParser that prints user readable errors.
static class	JavadocDetailNodeParser.ParseErrorMessage Contains information about parse error message.
static class	JavadocDetailNodeParser.ParseStatus Contains result of parsing javadoc comment: DetailNode tree and parse error message.

Field Summary

Fields

Modifier and Type	Field and Description
private int	blockCommentLineNumber Line number of the Block comment AST that is being parsed.
private static java.lang.String	JAVADOC_START Symbols with which javadoc starts.
static java.lang.String	MSG_JAVADOC_MISSED_HTML_CLOSE Message key of error message.
static java.lang.String	MSG_JAVADOC_PARSE_RULE_ERROR Parse error while rule recognition.
static java.lang.String	MSG_JAVADOC_WRONG_SINGLETON_TAG Message key of error message.
static java.lang.String	MSG_UNCLOSED_HTML_TAG Message property key for the Unclosed HTML message.

Constructor Summary

Constructors

Constructor and Description
JavadocDetailNodeParser()

Method Summary

Modifier and Type	Method and Description
private void	adjustFirstLineToJavadocIndent(DetailNode tree, int javadocColumnNumber) Adjust first line nodes to javadoc indent.
private DetailNode	convertParseTreeToDetailNode(org.antlr.v4.runtime.tree.ParseTree parseTreeNode) Converts ParseTree (that is generated by ANTLRv4) to DetailNode tree.
private static java.lang.String	convertUpperCamelToUpperUnderscore(java.lang.String text) Converts the given text from camel case to all upper case with underscores separating each word.
private JavadocNodeImpl[]	createChildrenNodes(JavadocNodeImpl parentJavadocNode, org.antlr.v4.runtime.tree.ParseTree parseTreeNode) Creates children Javadoc nodes base on ParseTree node's children.
private JavadocNodeImpl	createJavadocNode(org.antlr.v4.runtime.tree.ParseTree parseTree, DetailNode parent, int index) Creates JavadocNodeImpl node on base of ParseTree node.
private static com.puppycrawl.tools.checkstyle.grammar.javadoc.JavadocParser	createJavadocParser(java.lang.String blockComment, JavadocDetailNodeParser.DescriptiveErrorListener errorListener) Parses block comment content as javadoc comment.
private JavadocNodeImpl	createRootJavadocNode(org.antlr.v4.runtime.tree.ParseTree parseTreeNode) Creates root JavadocNodeImpl node base on ParseTree root node.
private static int	getColumn(org.antlr.v4.runtime.tree.ParseTree tree) Gets column number from ParseTree node.
private static org.antlr.v4.runtime.Token	getFirstNonTightHtmlTag(com.puppycrawl.tools.checkstyle.grammar.javadoc.JavadocParser javadocParser, int javadocLineOffset) This method is used to get the first non-tight HTML tag encountered while parsing javadoc.
private static java.lang.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.
private static int	getLine(org.antlr.v4.runtime.tree.ParseTree tree) Gets line number from ParseTree node.
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.
private static org.antlr.v4.runtime.tree.ParseTree	getNextSibling(org.antlr.v4.runtime.tree.ParseTree node) Gets next sibling of ParseTree node.
private static java.lang.String	getNodeClassNameWithoutContext(org.antlr.v4.runtime.tree.ParseTree node) Gets class name of ParseTree node and removes 'Context' postfix at the end.
private static int	getTokenType(org.antlr.v4.runtime.tree.ParseTree node) Gets token type of ParseTree node from JavadocTokenTypes class.
private void	insertChildrenNodes(JavadocNodeImpl[] nodes, org.antlr.v4.runtime.tree.ParseTree parseTreeParent) Creates child nodes for each node from 'nodes' array.
JavadocDetailNodeParser.ParseStatus	parseJavadocAsDetailNode(DetailAST javadocCommentAst) Parses Javadoc comment as DetailNode tree.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MSG_JAVADOC_MISSED_HTML_CLOSE

public static final java.lang.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:

Constant Field Values

MSG_JAVADOC_WRONG_SINGLETON_TAG

public static final java.lang.String MSG_JAVADOC_WRONG_SINGLETON_TAG

Message key of error message.

See Also:

Constant Field Values

MSG_JAVADOC_PARSE_RULE_ERROR

public static final java.lang.String MSG_JAVADOC_PARSE_RULE_ERROR

Parse error while rule recognition.

See Also:

Constant Field Values

MSG_UNCLOSED_HTML_TAG

public static final java.lang.String MSG_UNCLOSED_HTML_TAG

Message property key for the Unclosed HTML message.

See Also:

Constant Field Values

JAVADOC_START

private static final java.lang.String JAVADOC_START

Symbols with which javadoc starts.

See Also:

Constant Field Values

blockCommentLineNumber

private int blockCommentLineNumber

Line number of the Block comment AST that is being parsed.

Constructor Detail

JavadocDetailNodeParser

public JavadocDetailNodeParser()

Method Detail

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 com.puppycrawl.tools.checkstyle.grammar.javadoc.JavadocParser createJavadocParser(java.lang.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 java.lang.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 java.lang.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(com.puppycrawl.tools.checkstyle.grammar.javadoc.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 java.lang.String convertUpperCamelToUpperUnderscore(java.lang.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.