Issue checkstyle#410: Wiki-page .'�Tools To See Javadoc Tree Structur…

…e' part

src/xdocs/writingjavadocchecks.xml.vm

@@ -27,7 +27,123 @@
     <section name="Difference between Java Grammar and Javadoc comments Grammar">
     </section>
 
-    <section name="Javadoc tree structure">
+    <section name="Tools to see Javadoc tree structure">
+      <p>
+      Checkstyle can print Abstract Syntax Tree including Javadoc trees. You need to run checkstyle jar file with <b>-J</b> argument, providing java file.
+      </p>
+      <p>For example, here is java file:</p>
+      <source><![CDATA[
+/**
+ * My <b>class</b>.
+ * @see AbstractClass
+ */
+public class MyClass {
+
+}
+      ]]></source>
+      <p>Command:</p>
+      <source>java -jar checkstyle-6.18-all.jar -J MyClass.java</source>
+      <p>Output:</p>
+      <source><![CDATA[
+CLASS_DEF -> CLASS_DEF [5:0]
+|--MODIFIERS -> MODIFIERS [5:0]
+|   |--JAVADOC -> \r\n * My <b>class</b>.\r\n * @see AbstractClass\r\n <EOF> [1:0]
+|   |   |--NEWLINE -> \r\n [1:0]
+|   |   |--LEADING_ASTERISK ->  * [2:0]
+|   |   |--TEXT ->  My  [2:2]
+|   |   |   |--WS ->   [2:2]
+|   |   |   |--CHAR -> M [2:3]
+|   |   |   |--CHAR -> y [2:4]
+|   |   |   `--WS ->   [2:5]
+|   |   |--HTML_ELEMENT -> <b>class</b> [2:6]
+|   |   |   `--HTML_TAG -> <b>class</b> [2:6]
+|   |   |       |--HTML_ELEMENT_OPEN -> <b> [2:6]
+|   |   |       |   |--OPEN -> < [2:6]
+|   |   |       |   |--HTML_TAG_NAME -> b [2:7]
+|   |   |       |   `--CLOSE -> > [2:8]
+|   |   |       |--TEXT -> class [2:9]
+|   |   |       |   |--CHAR -> c [2:9]
+|   |   |       |   |--CHAR -> l [2:10]
+|   |   |       |   |--CHAR -> a [2:11]
+|   |   |       |   |--CHAR -> s [2:12]
+|   |   |       |   `--CHAR -> s [2:13]
+|   |   |       `--HTML_ELEMENT_CLOSE -> </b> [2:14]
+|   |   |           |--OPEN -> < [2:14]
+|   |   |           |--SLASH -> / [2:15]
+|   |   |           |--HTML_TAG_NAME -> b [2:16]
+|   |   |           `--CLOSE -> > [2:17]
+|   |   |--TEXT -> . [2:18]
+|   |   |   `--CHAR -> . [2:18]
+|   |   |--NEWLINE -> \r\n [2:19]
+|   |   |--LEADING_ASTERISK ->  * [3:0]
+|   |   |--WS ->   [3:2]
+|   |   |--JAVADOC_TAG -> @see AbstractClass\r\n  [3:3]
+|   |   |   |--SEE_LITERAL -> @see [3:3]
+|   |   |   |--WS ->   [3:7]
+|   |   |   |--REFERENCE -> AbstractClass [3:8]
+|   |   |   |   `--CLASS -> AbstractClass [3:8]
+|   |   |   |--NEWLINE -> \r\n [3:21]
+|   |   |   `--WS ->   [4:0]
+|   |   `--EOF -> <EOF> [4:1]
+|   `--LITERAL_PUBLIC -> public [5:0]
+|--LITERAL_CLASS -> class [5:7]
+|--IDENT -> MyClass [5:13]
+`--OBJBLOCK -> OBJBLOCK [5:21]
+    |--LCURLY -> { [5:21]
+    `--RCURLY -> } [7:0]
+      ]]></source>
+      <p>
+      As you see very small java file transforms to a huge Abstract Syntax Tree, because that is the most detailed tree including all components of the java file: classes, methods, comments, etc.
+      But in most cases while developing Javadoc Check you need only parse tree of the exact Javadoc comment.
+      To do that just copy Javadoc comment to separate file and remove <b>/**</b> at the begining and <b>*/</b> at the end. After that, run checkstyle with <b>-j</b> argument.
+      </p>
+      <p>File:</p>
+      <source><![CDATA[
+ * My <b>class</b>.
+ * @see AbstractClass
+      ]]></source>
+      <p>Command:</p>
+      <source>java -jar checkstyle-6.18-SNAPSHOT-all.jar -j MyJavadocComment.javadoc</source>
+      <p>Output:</p>
+      <source><![CDATA[
+JAVADOC ->  * My <b>class</b>.\r\n * @see AbstractClass<EOF> [0:0]
+|--LEADING_ASTERISK ->  * [0:0]
+|--TEXT ->  My  [0:2]
+|   |--WS ->   [0:2]
+|   |--CHAR -> M [0:3]
+|   |--CHAR -> y [0:4]
+|   `--WS ->   [0:5]
+|--HTML_ELEMENT -> <b>class</b> [0:6]
+|   `--HTML_TAG -> <b>class</b> [0:6]
+|       |--HTML_ELEMENT_OPEN -> <b> [0:6]
+|       |   |--OPEN -> < [0:6]
+|       |   |--HTML_TAG_NAME -> b [0:7]
+|       |   `--CLOSE -> > [0:8]
+|       |--TEXT -> class [0:9]
+|       |   |--CHAR -> c [0:9]
+|       |   |--CHAR -> l [0:10]
+|       |   |--CHAR -> a [0:11]
+|       |   |--CHAR -> s [0:12]
+|       |   `--CHAR -> s [0:13]
+|       `--HTML_ELEMENT_CLOSE -> </b> [0:14]
+|           |--OPEN -> < [0:14]
+|           |--SLASH -> / [0:15]
+|           |--HTML_TAG_NAME -> b [0:16]
+|           `--CLOSE -> > [0:17]
+|--TEXT -> . [0:18]
+|   `--CHAR -> . [0:18]
+|--NEWLINE -> \r\n [0:19]
+|--LEADING_ASTERISK ->  * [1:0]
+|--WS ->   [1:2]
+|--JAVADOC_TAG -> @see AbstractClass [1:3]
+|   |--SEE_LITERAL -> @see [1:3]
+|   |--WS ->   [1:7]
+|   `--REFERENCE -> AbstractClass [1:8]
+|       `--CLASS -> AbstractClass [1:8]
+`--EOF -> <EOF> [1:21]
+      ]]></source>
+
+
     </section>
 
     <section name="Token types">