Issue checkstyle#3311: Updated Documentation

voidfist · Jan 7, 2018 · ccefdd4 · ccefdd4
1 parent 66f3283
commit ccefdd4
Showing 1 changed file with 116 additions and 4 deletions.
diff --git a/src/xdocs/writingjavadocchecks.xml.vm b/src/xdocs/writingjavadocchecks.xml.vm
@@ -558,11 +558,123 @@ JAVADOC -> JAVADOC [0:0]
         </td>
       </tr>
     </table>
-    </section>
 
-    <section name="Boolean flag indicating the presence of unclosed HTML tags">
-      Not implemented yet, will be named "hasUnclosedTag". See <a href="https://github.com/checkstyle/checkstyle/issues/3311">Github Issue #3311</a>.
-      For expected behavior please read <a href="#Javadoc_parser_behavior_for_current_HTML_version_and_new_HTML_version">Javadoc parser behavior</a> section.
+    <p>
+        Checks can also be configured to log violation on encoutering non-tight HTML tags.
+        <tt>violateExecutionOnNonTightHtml</tt> property can be used for this purpose in the checks
+        that support it. A custom check needs to extend <tt>AbstractJavadocCheck</tt> for having
+        this functionality readily available. Do note that a check which has this property set to
+        true will log all violations upon finding non-tight HTML tags and then proceed to the
+        next javadoc. The following example illustrates how to use this property.
+    </p>
+
+    <p>
+    Input:
+    </p>
+
+    <source><![CDATA[
+/**
+  * <body>
+  * <p> This class is only meant for testing. </p>
+  * <p> In html, closing all tags is not necessary.
+  * <li> neither is opening every tag <p> </li>
+  * </body>
+  *
+  * @see "https://www.w3.org/TR/html51/syntax.html#optional-start-and-end-tags"
+  */
+ public class Test {
+     /** <p><p> paraception </p> </p> */
+     private int field1;
+
+     /**<li> paraTags should be opened</p> list isn't nested in parse tree </li>*/
+     private int field2;
+
+     /**
+      * <p> this paragraph is closed and would be nested in javadoc tree </p>
+      * <li> this list has an <p> unclosed para, but still the list would get nested </li>
+      */
+     private int field3;
+
+     /**
+      * <li> Complete <p> nesting </p> </li>
+      * <tr> Zero </p> nesting despite `tr` is closed </tr>
+      */
+     private int field4;
+}
+    ]]></source>
+
+    <p>
+        Output with <tt>violateExecutionOnNonTightHtml</tt> set to false:
+    </p>
+
+    <table>
+      <tr>
+        <td>
+          <source><![CDATA[
+<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC
+"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
+"http://www.puppycrawl.com/dtds/configuration_1_3.dtd">
+<module name="Checker">
+  <property name="charset" value="UTF-8"/>
+    <module name="TreeWalker">
+      <module name="JavadocParagraph">
+        <property name="violateExecutionOnNonTightHtml" value="false"/>
+      </module>
+    </module>
+</module>
+          ]]></source>
+        </td>
+
+        <td>
+          <source><![CDATA[
+Starting audit...
+[ERROR] Test.java:11: Redundant <p> tag. [JavadocParagraph]
+Audit done.
+Checkstyle ends with 1 errors.
+          ]]></source>
+        </td>
+      </tr>
+    </table>
+
+    <p>
+        Output with <tt>violateExecutionOnNonTightHtml</tt> set to true:
+    </p>
+
+    <table>
+      <tr>
+        <td>
+          <source><![CDATA[
+<?xml version="1.0"?>
+<!DOCTYPE module PUBLIC
+"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
+"http://www.puppycrawl.com/dtds/configuration_1_3.dtd">
+<module name="Checker">
+<property name="charset" value="UTF-8"/>
+<module name="TreeWalker">
+<module name="JavadocParagraph">
+<property name="violateExecutionOnNonTightHtml" value="true"/>
+</module>
+</module>
+</module>
+          ]]></source>
+        </td>
+
+        <td>
+          <source><![CDATA[
+Starting audit...
+[ERROR] Test.java:4: Unclosed HTML tag found: p [JavadocParagraph]
+[ERROR] Test.java:11: Redundant <p> tag. [JavadocParagraph]
+[ERROR] Test.java:11: Unclosed HTML tag found: p [JavadocParagraph]
+[ERROR] Test.java:14: Unclosed HTML tag found: li [JavadocParagraph]
+[ERROR] Test.java:19: Unclosed HTML tag found: p [JavadocParagraph]
+[ERROR] Test.java:25: Unclosed HTML tag found: tr [JavadocParagraph]
+Audit done.
+Checkstyle ends with 6 errors.
+          ]]></source>
+        </td>
+      </tr>
+    </table>
     </section>
 
     <section name="Checkstyle SDK GUI">