From 1ef75b520f27e67eb96fc44de81e62889289d3b0 Mon Sep 17 00:00:00 2001 From: Baratali Izmailov Date: Thu, 12 May 2016 23:24:23 +0100 Subject: [PATCH] Issue #410: Writing JavadocChecks wiki-page. Classes and methods as links --- src/xdocs/writingjavadocchecks.xml.vm | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/src/xdocs/writingjavadocchecks.xml.vm b/src/xdocs/writingjavadocchecks.xml.vm index dc312b43e..11597baa6 100644 --- a/src/xdocs/writingjavadocchecks.xml.vm +++ b/src/xdocs/writingjavadocchecks.xml.vm @@ -66,19 +66,17 @@ public class MyClass {

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

- In Javadoc comment every whitespace matters, so parse tree contains whitespace nodes (WS javadoc token type). - So do CHAR javadoc token that presents single character. The only redundancy Javadoc tree has because of this is that TEXT node - consists of CHAR and WS nodes which is useless, but it is implementation nuance. (In future we will try to resolve this). + In Javadoc comment every whitespace matters, so parse tree contains whitespace nodes (WS javadoc token type). + So do CHAR javadoc token that presents single character. The only redundancy Javadoc tree has because of this is that TEXT node consists of CHAR and WS nodes which is useless, but it is implementation nuance. (In future we will try to resolve this).

@@ -91,7 +89,7 @@ public class MyClass {

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. + Java AST consists of DetailAST objects, while Javadoc AST consists of DetailNode objects.

@@ -110,7 +108,7 @@ public class MyClass { } ]]>

Command:

- java -jar checkstyle-6.18-all.jar -J MyClass.java + java -jar checkstyle-X.XX-all.jar -J MyClass.java

Output:

CLASS_DEF [5:0] @@ -171,7 +169,7 @@ CLASS_DEF -> CLASS_DEF [5:0] * @see AbstractClass ]]>

Command:

- java -jar checkstyle-6.18-SNAPSHOT-all.jar -j MyJavadocComment.javadoc + java -jar checkstyle-X.XX-all.jar -j MyJavadocComment.javadoc

Output:

* My class.\r\n * @see AbstractClass [0:0] @@ -214,9 +212,9 @@ 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 from Javadoc Check. - You may need this block comment to check its position or something else in main DetailAST tree. + 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. + 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.

Example: @@ -371,7 +369,7 @@ 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. + Javadoc Checks as well as regular Checks extend AbstractCheck class. So integrating new Javadoc Check is similar to integrating other Checks.