From ff6526252e03136ef899263be8e65967d71ed0ee Mon Sep 17 00:00:00 2001 From: Baratali Izmailov Date: Sat, 14 May 2016 14:43:35 +0100 Subject: [PATCH] Issue #410: WritingJavadocChecks wiki-page. Some amendments. --- src/xdocs/writingjavadocchecks.xml.vm | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/src/xdocs/writingjavadocchecks.xml.vm b/src/xdocs/writingjavadocchecks.xml.vm index 585c143e9..6d4d6d064 100644 --- a/src/xdocs/writingjavadocchecks.xml.vm +++ b/src/xdocs/writingjavadocchecks.xml.vm @@ -52,14 +52,15 @@ public class MyClass { The comment should be written in XHTML to be correctly processed by Checkstyle. This means that every HTML tag should have matching closed HTML tag or it is self-closed one (singlton tag). The only exceptions are <p>, <li>, <tr>, <td>, <th>, <body>, <colgroup>, <dd>, <dt>, <head>, <html>, <option>, <tbody>, <thead>, <tfoot> and Checkstyle won't show error about missing closing tag, however, it leads to broken XHTML structure and, therefore, - incorrect Abstract Syntax Tree of the Javadoc comment anyway. See examples at "HTML Code In Javadoc Comments" chapter. + not-nested content of the HTML tags in Abstract Syntax Tree of the Javadoc comment. See examples at "HTML Code In Javadoc Comments" chapter.

Javadoc parser requires XHTML to be used in Javadoc comments, i.e. if there is some open tag(for example <div>) then there have to be its close tag </div>. This means that if Javadoc comment has incorrect XHTML structure then Javadoc Parser will fail processing the comment, therefore, your new Check can't get its parse tree and process anything from this Javadoc comment. For more details and examples go to "HTML code in Javadoc comments" section.

- Javadoc grammar requires XHTML, but it can also parse some parts of HTML code (like some unclosed tags). However result tree will be unpredictable. + Javadoc grammar requires XHTML, but it can also parse some parts of HTML code (like some unclosed tags). If HTML tags are not closed Javadoc grammar cannot determine content of these tags, + so structure of the parse tree will not be nested like it is while using XHTML. It is done just to not fail on every Javadoc comment, because there are tons of using unclosed tags, etc.

@@ -73,17 +74,6 @@ public class MyClass { There is also TokenTypes class in Checkstyle. Make sure you use JavadocTokenTypes class in your Check, because the TokenTypes is used to describe standard Java DetailAST token type.
  • visitJavadocToken(DetailNode) - it's the place you should put tree nodes proccessing. The argument is Javadoc tree node of type you described before in getDefaultJavadocTokens() method.
    • - -

    - In Javadoc comment every whitespace matters, so parse tree contains whitespace nodes - (WS javadoc token type). - So do CHAR javadoc token that presents single character. - The only redundancy Javadoc tree has because of this is that - TEXT node consists of - CHAR and - WS nodes which is useless, but it is implementation nuance. - (In future we will try to resolve this. See Github Issue #3170). -

    @@ -97,6 +87,17 @@ public class MyClass { The problem is that Java grammar is old one and uses ANTLR v2, while Javadoc grammar uses ANTLR v4. Because of that, these two grammars and their trees are not compatible. Java AST consists of DetailAST objects, while Javadoc AST consists of DetailNode objects.

    +

    + Main Java grammar skips any whitespaces and newlines, so in Java Abstract Syntax Tree there are no whitespace/newline nodes. + In Javadoc comment every whitespace matters, and Javadoc Checks need all those whitespaces and newline nodes to verify format and content of the Javadoc comment. + Because of that Javadoc grammar includes all whitespaces, newlines to the parse tree + (WS, NEWLINE). + As you may notice there is also CHAR javadoc token that presents single character. + It is quite useless and is used for building only TEXT node which consists of + CHAR and + WS nodes, but it is implementation nuance. + (In future we will try to resolve this. See Github Issue #3170). +