diff --git a/src/xdocs/writingchecks.xml.vm b/src/xdocs/writingchecks.xml.vm index c9762b155..48e16ecad 100644 --- a/src/xdocs/writingchecks.xml.vm +++ b/src/xdocs/writingchecks.xml.vm @@ -156,11 +156,12 @@ java -cp checkstyle-${projectVersion}-all.jar com.puppycrawl.tools.checkstyle.gu

Ready for a bit more theory? The last bit that is missing before you can start writing Checks is understanding - the Visitor pattern. + the Visitor pattern.

- When working with ASTs, a simple approach to define check operations + When working with + Abstract Syntax Tree (AST), a simple approach to define check operations on them would be to add a check() method to the Class that defines the AST nodes. For example, our AST type could have a method checkNumberOfMethods(). Such an approach would suffer from a few @@ -182,7 +183,8 @@ java -cp checkstyle-${projectVersion}-all.jar com.puppycrawl.tools.checkstyle.gu href="apidocs/com/puppycrawl/tools/checkstyle/api/Check.html#visitToken(com.puppycrawl.tools.checkstyle.api.DetailAST)">visitToken().

It is important to understand that the individual - Checks do no drive the AST traversal. Instead, the TreeWalker initiates + Checks do no drive the AST traversal (it possible to traverse itself, but not recommended). + Instead, the TreeWalker initiates a recursive descend from the root of the AST to the leaf nodes and calls the Check methods. The traversal is done using a depth-first @@ -201,13 +203,6 @@ java -cp checkstyle-${projectVersion}-all.jar com.puppycrawl.tools.checkstyle.gu been left, the TreeWalker will call finishTree().

-

- If you'd like to learn more about the Visitor pattern you should - grab a copy of the Gof - Design - Patterns book. -

-
@@ -251,13 +246,15 @@ public class MethodLimitCheck extends Check { // find the OBJBLOCK node below the CLASS_DEF/INTERFACE_DEF DetailAST objBlock = ast.findFirstToken(TokenTypes.OBJBLOCK); + // count the number of direct children of the OBJBLOCK // that are METHOD_DEFS int methodDefs = objBlock.getChildCount(TokenTypes.METHOD_DEF); + // report error if limit is reached if (methodDefs > this.max) { - log(ast.getLineNo(), - "too many methods, only " + this.max + " are allowed"); + String message = "too many methods, only " + this.max + " are allowed"; + log(ast.getLineNo(), message); } } } @@ -272,7 +269,7 @@ public class MethodLimitCheck extends Check provides utility methods to extract information from the tree, like getChildCount(). By now you have probably consulted the API documentation and found that - DetailsAST additionally provides methods for navigating around + DetailsAST additionally provides methods for navigating around in the syntax tree, like finding the next sibling of a node, the children of a node, the parent of a node, etc.

@@ -322,8 +319,8 @@ public class MethodLimitCheck extends Check

With this code added, you can set the property max for the MethodLimitCheck module in the configuration file. It doesn't get any simpler than that. The secret is - that Checkstyle uses JavaBean introspection to set the JavaBean - properties. That works for all primitive types like boolean, + that Checkstyle uses + JavaBean reflection to set the JavaBean properties. That works for all primitive types like boolean, int, long, etc., plus Strings, plus arrays of these types.

@@ -351,8 +348,10 @@ public class MethodLimitCheck extends Check

- To support internationalized error messages, you need to create - a messages.properties file alongside your Check class, i.e. the + To support internationalized error messages, you need to create or reuse existing + a messages.properties file alongside your Check class + (example) + , i.e. the Java file and the properties files should be in the same directory. Add a symbolic error code and an English representation to the messages.properties. The file should @@ -384,7 +383,7 @@ public class MethodLimitCheck extends Check Check. To integrate your Check, add a new subentry under the TreeWalker module of your configuration file. Use the full classname of your Check class as the name of the module. - Your configuration file should look something like this: + Your configuration file config.xml should look something like this:

@@ -414,7 +413,6 @@ public class MethodLimitCheck extends Check java -classpath mycompanychecks.jar:checkstyle-${projectVersion}-all.jar \ - com.puppycrawl.tools.checkstyle.Main \ -c config.xml -r . @@ -444,24 +442,38 @@ java -classpath mycompanychecks.jar:checkstyle-${projectVersion}-all.jar \

- There are basically only two of them: + There are basically only few of them:

This means that you cannot implement some of the code inspection features that are available in advanced IDEs like IntelliJ IDEA. For - example you will not be able to implement a Check that finds - redundant type casts or unused public methods. + href="http://www.intellij.com/idea/">IntelliJ IDEA, + Findbug, + PMD, + Sonarqube.

+

+ For example you will not be able to implement: +
+ - a Check that finds redundant type casts or unused public methods. +
+ - a Check that validate that user custom Exception class inherited from java.lang.Exception class. +

+ +

Writing a FileSetCheck usually required when you do not need parse Java file + to get inner structure, or you are going to validate non "*.java" files. +

Writing a FileSetCheck is pretty straightforward: Just inherit from

There are virtually no limits what you can do in - FileSetChecks. The craziest ideas we've had so far are: + FileSetChecks, but please do not be creazy.

-
@@ -535,7 +541,8 @@ public class LimitImplementationFiles extends AbstractFileSetCheck

That's probably our fault, and it means that we have to provide better documentation. Please do not hesitate to ask questions on - the user mailing list, this will help us to improve this + the user + mailing lists, this will help us to improve this document. Please ask your questions as precisely as possible. We will not be able to answer questions like "I want to write a Check but I don't know how, can you help me?". Tell