TouchInstinct
/
checkstyle
307
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Issue #410: Some amendments in WritingJavadocCheck

This commit is contained in:
Baratali Izmailov 2016-05-20 09:52:49 -07:00 committed by Roman Ivanov
parent 93acc4e083
commit ca2e975558
1 changed files with 20 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
src/xdocs/writingjavadocchecks.xml.vm
View File

@ -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 <a href="#HTML_Code_In_Javadoc_Comments">HTML Code In Javadoc Comments</a> section.
</p>
<p>
Javadoc parser requires XHTML to be used in Javadoc comments, i.e. if there is some open tag(for example &lt;div&gt;) then there have to be its close tag &lt;/div&gt;.
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 <a href="#HTML_Code_In_Javadoc_Comments">HTML Code In Javadoc Comments</a> 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 <a href="#HTML_Code_In_Javadoc_Comments">HTML Code In Javadoc Comments</a> section.
</p>
<p>
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 {
</p>
</section>
<section name="Overview">
<section name="How to create Javadoc Check">
<p>
Principle of writing Javadoc Checks is similar to writing regular Checks. You just extend another class and use another token types.
</p>
<p>
To start implementing new Check create new class and extend <a href='apidocs/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.html'>AbstractJavadocCheck</a>. It has two abstract methods you should implement:
</p>
@ -261,7 +259,20 @@ class MyCheck extends AbstractJavadocCheck {
<section name="HTML Code In Javadoc Comments">
<p>
Checkstyle supports HTML4 tags in Javadoc comments: <a href="https://www.w3.org/TR/html4/index/elements.html">all HTML4 elements</a>.
However if Checkstyle meets unknown tag (for example HTML5 tag)
</p>
<p>
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.
</p>
<p>
Tags that don't require closing tag: &lt;P&gt;, &lt;LI&gt;, &lt;TR&gt;, &lt;TD&gt;, &lt;TH&gt;, &lt;BODY&gt;, &lt;COLGROUP&gt;, &lt;DD&gt;,
&lt;DT&gt;, &lt;HEAD&gt;, &lt;HTML&gt;, &lt;OPTION&gt;, &lt;TBODY&gt;, &lt;THEAD&gt;, &lt;TFOOT&gt;.
</p>
<p>
Singleton tags that don't need closing tag: &lt;AREA&gt;, &lt;BASE&gt;, &lt;BASEFONT&gt;, &lt;BR&gt;, &lt;COL&gt;, &lt;FRAME&gt;,
&lt;HR&gt;, &lt;IMG&gt;, &lt;INPUT&gt;, &lt;ISINDEX&gt;, &lt;LINK&gt;, &lt;META&gt;, &lt;PARAM&gt;.
</p>
<p>
If Checkstyle meets unknown tag (for example HTML5 tag)
it doesn't fail and parses this tag as <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#HTML_TAG">HTML_TAG</a> Javadoc token type.
Just follow XHTML rules to make Checkstyle javadoc parser happy, even though tags are unknown.