From ca2e97555897ca492433989e41fc5e6f542b3c84 Mon Sep 17 00:00:00 2001 From: Baratali Izmailov Date: Fri, 20 May 2016 09:52:49 -0700 Subject: [PATCH] Issue #410: Some amendments in WritingJavadocCheck --- src/xdocs/writingjavadocchecks.xml.vm | 29 ++++++++++++++++++--------- 1 file changed, 20 insertions(+), 9 deletions(-) diff --git a/src/xdocs/writingjavadocchecks.xml.vm b/src/xdocs/writingjavadocchecks.xml.vm index 586ef7fb9..41f6b846a 100644 --- a/src/xdocs/writingjavadocchecks.xml.vm +++ b/src/xdocs/writingjavadocchecks.xml.vm @@ -52,13 +52,8 @@ public class MyClass { Javadoc by specification could contain any HTML tags that let user generate content he needs. Checkstyle can not parse something that looks like an HTML, so limitation appear. 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 to - not-nested content of the HTML tags in Abstract Syntax Tree of the Javadoc comment. See examples at HTML Code In Javadoc Comments section. -

-

- 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. + The only exceptions are HTML 4 tags that don't require closing tag and HTML 4 singleton tags, so, Checkstyle won't show error about missing closing tag, however, it leads to broken XHTML structure and to + not-nested content of the HTML tags in Abstract Syntax Tree of the Javadoc comment. More details about HTML at HTML Code In Javadoc Comments section.

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, @@ -67,7 +62,10 @@ public class MyClass {

-
+
+

+ Principle of writing Javadoc Checks is similar to writing regular Checks. You just extend another class and use another token types. +

To start implementing new Check create new class and extend AbstractJavadocCheck. It has two abstract methods you should implement:

@@ -261,7 +259,20 @@ class MyCheck extends AbstractJavadocCheck {

Checkstyle supports HTML4 tags in Javadoc comments: all HTML4 elements. - However if Checkstyle meets unknown tag (for example HTML5 tag) +

+

+ HTML 4 is picked just to have a list of tags that don't require closing tag and a list of singleton tags that don't need closing tag at all. +

+

+ Tags that don't require closing tag: <P>, <LI>, <TR>, <TD>, <TH>, <BODY>, <COLGROUP>, <DD>, + <DT>, <HEAD>, <HTML>, <OPTION>, <TBODY>, <THEAD>, <TFOOT>. +

+

+ Singleton tags that don't need closing tag: <AREA>, <BASE>, <BASEFONT>, <BR>, <COL>, <FRAME>, + <HR>, <IMG>, <INPUT>, <ISINDEX>, <LINK>, <META>, <PARAM>. +

+

+ If Checkstyle meets unknown tag (for example HTML5 tag) it doesn't fail and parses this tag as HTML_TAG Javadoc token type. Just follow XHTML rules to make Checkstyle javadoc parser happy, even though tags are unknown.