Editing Cs-doclet (section)

== Extending CheckStyle ==

CheckStyle comes with an API to [http://checkstyle.sourceforge.net/writingchecks.html extend] it with custom checks and filters. Here is a completely useless, yet typical example of a custom check:

'''File "src/com/pany/cs/checks/ColorCheck.java":'''
 package com.pany.cs.checks;
 
 import com.puppycrawl.tools.checkstyle.api.Check;
 import com.puppycrawl.tools.checkstyle.api.DetailAST;
 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
 
 public
 class ColorCheck extends Check {
 
     public void
     setColor(String value) { this.color = value; }
     private String color = "Yellow";
 
     @Override public int[]
     getDefaultTokens() { return new int[] { TokenTypes.ANNOTATION }; }
 
     @Override public void
     visitToken(DetailAST ast) { this.log(ast, "theColorIs", this.color); }
 }

The CheckStyle extension API supports internationalization be means of "messages.properties" files:

'''File "src/com/pany/cs/checks/messages.properties":'''
 theColorIs = The color is ''{0}''

'''File "src/com/pany/cs/checks/messages_de.properties":'''
 theColorIs = Die Farbe ist ''{0}''

To make use of this check, you'd write a "CheckStyle configuration file"

'''File "checkstyle-config.xml":'''
 <?xml version="1.0" encoding="UTF-8"?>
 <!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="severity" value="warning" />
   <module name="TreeWalker">
     <module name="com.pany: ColorCheck">
       <property name="color" value="blue" />
     </module>
   </module>
 </module>

, and execute CheckStyle on a target project, e.g. on the example project itself:

 $ javac -d bin src/com/pany/cs/checks/ColorCheck.java
 $ java -classpath '<span style="color:red">bin</span>;path/to/checkstyle-6.1-all.jar' \
 > com.puppycrawl.tools.checkstyle.Main \
 > -c checkstyle-config.xml \
 > -r src
 Starting audit...
 C:\dev\EclipseWS\de.unkrig.cs-contrib\foo\src\com\pany\cs\checks\ColorCheck.java:14:5: warning: The color is 'blue'
 C:\dev\EclipseWS\de.unkrig.cs-contrib\foo\src\com\pany\cs\checks\ColorCheck.java:17:5: warning: The color is 'blue'
 Audit done.
 $

(We get the two warnings because there are two "@Override" annotations in the code.)

Obviously, the Java code and the "messages.properties" files must be kept in sync with the Java code at all times, which is naturally very error-prone.

Cs-doclet facilitates the task by generating the "messages.properties" file from annotations in the source code:

'''File "src/com/pany/cs/checks/MyCheck.java":'''
 package com.pany.cs.checks;
 
 import com.puppycrawl.tools.checkstyle.api.Check;
 import com.puppycrawl.tools.checkstyle.api.DetailAST;
 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
 
 public
 class ColorCheck extends Check {
 
     <span style="color:red">@Message("The color is ''{0}''")
     private static final String MESSAGE_KEY_THE_COLOR_IS = "theColorIs";</span>
 
     public void
     setColor(String value) { this.color = value; }
     private String color = "Yellow";
 
     @Override public int[]
     getDefaultTokens() { return new int[] { TokenTypes.ANNOTATION }; }
 
     @Override public void
     visitToken(DetailAST ast) { this.log(ast, <span style="color:red">MESSAGE_KEY_THE_COLOR_IS</span>, this.color); }
 }

To generate the "messages.properties" file, you'd run JAVADOC with the cs-doclet and the "-messages.properties-dir" command line option:
 $ javadoc \
 > <span style="color:red">-doclet de.unkrig.doclet.cs.CsDoclet</span> \
 > <span style="color:red">-docletpath "path/to/cs-doclet.jar;bin;path/to/checkstyle-6.1-all.jar;path/to/net.sf.eclipsecs.core-6.1.jar"</span> \
 > <span style="color:red">-messages.properties-dir src</span> \
 > -sourcepath src \
 > -classpath ../net.sf.checkstyle-6.1/checkstyle-6.1/checkstyle-6.1-all.jar \
 > com.pany.cs.checks
 Loading source files for package com.pany.cs.checks...
 Constructing Javadoc information...
 $

Notice that both "checkstyle.jar" and "net.sf.eclipsecs-core.jar" must be on the "-docletpath".

The generated "src/com/pany/cs/checks/messages.properties" file looks like this:

 # This file was generated by the CS doclet; see http://cs-doclet.unkrig.de/
 
 # Custom check messages, in alphabetical order.
 
 # --------------- com.pany: ColorCheck ---------------
 <span style="color:red">theColorIs</span> = <span style="color:red">The color is ''{0}''</span>

And voilà! All the messages are where they belong: In the source code.