diff --git a/src/xdocs/writingjavadocchecks.xml.vm b/src/xdocs/writingjavadocchecks.xml.vm index e73a8714f..0cb862a91 100644 --- a/src/xdocs/writingjavadocchecks.xml.vm +++ b/src/xdocs/writingjavadocchecks.xml.vm @@ -23,34 +23,63 @@

- Javadoc comment is multiline comment that starts with * character and placed under class definition, interface definition, enum definition, method definition or field definition. - 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. + Javadoc comment is multiline comment that starts with * character and placed above class definition, interface definition, enum definition, method definition or field definition. +

For example, here is java file:

+ class. + * @see AbstractClass + */ +public class MyClass { + +} + ]]> + Javadoc content is: + class. + * @see AbstractClass + ]]>

+ Attention that java comment is start with /*, following with Identificator of comment type. Javadoc Identificator is *. All symbols after Javadoc Identificator till */ are part of javadoc comment. In internet you can find different types of documentation + generation tools similar to javadoc. Such tools reply on different Identificators: "!", "#", "$". + Comments looks like "/*! some comment */" , "/*# some comment */" , "/*$ some comment */". Such multiline comments are not a javadoc.
-
+

- To start implementing your own Check create new class and extend AbstractJavadocCheck. It has two abstract methods you should implement: + Javadoc by specification could contain any HTML tags that to let user generate content hi 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, therefore, + incorrect Abstract Syntax Tree of the Javadoc comment anyway. 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.

+
+

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

+ +
+

- Java grammar parses java file due to language specifications. So, there are singleline comments and multiline/block comments in it. Java compiler doesn't know about Javadoc because it is just a multiline comment. - To parse multiline comment as a Javadoc comment, checkstyle has second grammar - Javadoc grammar. So, it's supposed to proccess block comments and parse them to Abstract Syntax Tree. + Java grammar parses java file due to Java language specifications. So, there are singleline comments and multiline/block comments in it. Java compiler doesn't know about Javadoc because it is just a multiline comment. + To parse multiline comment as a Javadoc comment, checkstyle has special Parser + that is based on ANTLR Javadoc grammar. So, it's supposed to proccess block comments + that start with Javadoc Identificator and parse them to Abstract Syntax Tree (AST). +

+

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.

@@ -58,9 +87,9 @@

- Checkstyle can print Abstract Syntax Tree including Javadoc trees. You need to run checkstyle jar file with -J argument, providing java file. + Checkstyle can print Abstract Syntax Tree for Java and Javadoc trees. You need to run checkstyle jar file with -J argument, providing java file.

-

For example, here is java file:

+

For example, here is MyClass.java file:

class. @@ -126,7 +155,7 @@ CLASS_DEF -> CLASS_DEF [5:0] 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 /** at the begining and */ at the end. After that, run checkstyle with -j argument.

-

File:

+

MyJavadocComment.javadoc file:

class. * @see AbstractClass @@ -174,14 +203,17 @@ JAVADOC -> * My class.\r\n * @see AbstractClass [0:0]
- As you alreasy know Javadoc parse tree is result of parsing block comment. There is a method to get the original block comment. - You may need this block comment to check its position or something else in main DetailAST tree. For example, to write a JavadocCheck that verifies @param tags in Javadoc comment of a method definition, you also need all method's parameter names. To get method definition AST you should access main DetailAST tree throuth block comment AST. For this purpose use getBlockCommentAst() method that returns DetailAST node. + As you alreasy know Javadoc parse tree is result of parsing block comment. There is a method to get the original block comment from Javadoc Check. + You may need this block comment to check its position or something else in main DetailAST tree. +

+ For example, to write a JavadocCheck that verifies @param tags in Javadoc comment of a method definition, you also need all method's parameter names. To get method definition AST you should access main DetailAST tree throuth block comment AST. For this purpose use getBlockCommentAst() method that returns DetailAST node. +

Examples: - 1) Unclosed paragraph HTML tag. As you see in the tree, content of the paragraph tag is not nested to this tag. That is because HTML tags are not closed by pair tag </p>, and Checkstyle requires XHTML to correctly parse Javadoc comments. + 1) Unclosed paragraph HTML tag. As you see in the tree, content of the paragraph tag is not nested to this tag. That is because HTML tags are not closed by pair tag </p>, and Checkstyle requires XHTML to predictably parse Javadoc comments.

First @@ -218,7 +250,7 @@ JAVADOC ->

First\r\n

Second [0:0] `--EOF -> [1:10] ]]>

- 2) Here is correct version with open and closed HTML tags. + 2) Here is correct version with open and closed HTML tags.

First

@@ -278,5 +310,12 @@ JAVADOC ->

First

\r\n

Second

[0:0] Javadoc Checks as well as regular Checks extend AbstractCheck class. So integrating new Javadoc Check is similar to integrating other Checks.
+
+ The best source knowledge about how to write Javadoc Checks + could be taken from + + existing Checks. +
+