Editing Cs-doclet

<meta name="keywords" content="java, doclet, javadoc, checkstyle"></meta>
<meta name="description" content="A doclet that generates the metadata files for CHECKSTYLE and ECLIPSE-CS from annotations and DOC tags in the source code of the checks and filters"></meta>
== Abstract ==

Cs-doclet is a [http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/ JAVADOC doclet] that generates the metadata files for [http://checkstyle.sourceforge.net/ CheckStyle] and [http://eclipse-cs.sourceforge.net/ eclipse-cs] from annotations and 'doc tags' in the source code of your checks and filters.

== Intended audience ==

This tool is useful for the development of [http://checkstyle.sourceforge.net/ CheckStyle] checks and filters, and for their integration in [http://eclipse-cs.sourceforge.net/ eclipse-cs] and [http://www.mediawiki.org/wiki/MediaWiki MediaWiki].

== 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-contrib.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.

== Integrating with eclipse-cs ==

When you integrate your checks with eclipse-cs, then you learn that you have to write two more metadata files:

'''File "checkstyle-metadata.xml":'''
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE checkstyle-metadata PUBLIC
 "-//eclipse-cs//DTD Check Metadata 1.1//EN"
 "http://eclipse-cs.sourceforge.net/dtds/checkstyle-metadata_1_1.dtd">
 <checkstyle-metadata>
 
     <rule-group-metadata name="%Whitespace.group" priority="999">
         <rule-metadata
             internal-name="com.pany.cs.checks.ColorCheck"
             parent="TreeWalker"
             name="%ColorCheck.name"
         >
             <alternative-name internal-name="com.pany.cs.checks.ColorCheck" />
             <description>%ColorCheck.desc</description>
 
             <property-metadata
                 name="color"
                 datatype="String"
                 default-value="Yellow"
             >
                 <description>%ColorCheck.color</description>
             </property-metadata>
             <message-key key="theColorIs" />
         </rule-metadata>
     </rule-group-metadata>
 </checkstyle-metadata>

'''File "checkstyle-metadata.properties":'''
 Whitespace.group = Whitespace
 ColorCheck.name = com.pany: ColorCheck
 ColorCheck.desc =\
     A completely useless check which merely prints a (localizable) message each \
     time it encounters an annotation.
 ColorCheck.color = A completely useless check parameter.

Tedious, isn't it? Well, you can tell cs-doclet to also generate ''these'' files from annotations (and doc comments):

'''File "src/com/pany/cs/checks/MyCheck.java":'''
 // File "src/com/pany/cs/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;
 
 import de.unkrig.csdoclet.StringRuleProperty;
 import de.unkrig.csdoclet.Rule;
 
 /**
  * <span style="color:red">A completely useless check which merely prints a</span>
  * <span style="color:red">(localizable) message each time it encounters an annotation.</span>
  */
 <span style="color:red">@Rule(
     group      = "%Whitespace.group",
     groupName  = "Whitespace",
     name       = "com.pany: ColorCheck",
     parent     = "TreeWalker"
 )</span>
 public
 class ColorCheck extends Check {
 
     @Message("The color is ''{0}''")
     private static final String MESSAGE_KEY_THE_COLOR_IS = "theColorIs";
 
     /**
      * <span style="color:red">A completely useless check parameter</span>.
      */
     <span style="color:red">@StringRuleProperty(defaultValue = DEFAULT_COLOR)</span>
     public void
     setColor(String value) { this.color = value; }
 
     private String color = <span style="color:red">DEFAULT_COLOR</span>;
 
     <span style="color:red">private static final String DEFAULT_COLOR = "Yellow";</span>
 
     @Override public int[]
     getDefaultTokens() { return new int[] { TokenTypes.ANNOTATION }; }
 
     @Override public void
     visitToken(DetailAST ast) { this.log(ast, MESSAGE_KEY_THE_COLOR_IS, this.color); }
 }

 $ javadoc \
 > -doclet de.unkrig.doclet.cs.CsDoclet \
 > -docletpath "path/to/cs-doclet.jar;bin;path/to/checkstyle-6.1-all.jar;path/to/net.sf.eclipsecs.core-6.1.jar" \
 > <span style="color:red">-checkstyle-metadata.properties-dir src</span> \
 > <span style="color:red">-checkstyle-metadata.xml-dir src</span> \
 > -messages.properties-dir src \
 > -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...
 $

And you'll get:

'''File "src/com/pany/cs/checks/checkstyle-metadata.properties":'''
 # This file was generated by the CS doclet; see http://cs-contrib.unkrig.de.
 
 # Rule groups:
 <span style="color:red">Whitespace.group</span> = <span style="color:red">Whitespace</span>
 
 # Custom checks, in alphabetical order.
 
 # --------------- <span style="color:red">com.pany: ColorCheck</span> ---------------
 
 <span style="color:red">ColorCheck.name</span> = <span style="color:red">com.pany: ColorCheck</span>
 <span style="color:red">ColorCheck.desc</span> =\
     <span style="color:red">A completely useless check which merely prints a (localizable) message each time it encounters an annotation.</span>
 <span style="color:red">ColorCheck.color</span>                                  = <span style="color:red">A completely useless check parameter.</span>

'''File "src/com/pany/cs/checks/checkstyle-metadata.xml":'''
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE checkstyle-metadata PUBLIC
 "-//eclipse-cs//DTD Check Metadata 1.1//EN"
 "http://eclipse-cs.sourceforge.net/dtds/checkstyle-metadata_1_1.dtd">
 <checkstyle-metadata>
 
     &lt;!-- This file was generated by the CS doclet; see http://cs-contrib.unkrig.de -->
 
     &lt;!-- ColorCheck -->
 
     <rule-group-metadata name="<span style="color:red">%Whitespace.group</span>" priority="999">
         <rule-metadata
             internal-name="<span style="color:red">com.pany.cs.checks.ColorCheck</span>"
             parent="<span style="color:red">TreeWalker</span>"
             name="<span style="color:red">%ColorCheck.name</span>"
         >
             <alternative-name internal-name="<span style="color:red">com.pany.cs.checks.ColorCheck</span>" />
             <description><span style="color:red">%ColorCheck.desc</span></description>
 
             <property-metadata
                 name="<span style="color:red">color</span>"
                 datatype="<span style="color:red">String</span>"
                 default-value="<span style="color:red">Yellow</span>"
             >
                 <description><span style="color:red">%ColorCheck.color</span></description>
             </property-metadata>
             <message-key key="theColorIs" />
         </rule-metadata>
     </rule-group-metadata>
 </checkstyle-metadata>

== MediaWiki markup documentation ==

Typically, you will also want to publish human-readable documentation for your checks and filters, which is more or less identical with the text in the eclipse-cs metadata files. This is also possible with the "-mediawiki-dir" command line option:

 $ javadoc \
 > -doclet de.unkrig.doclet.cs.CsDoclet \
 > -docletpath "path/to/cs-doclet.jar;bin;path/to/checkstyle-6.1-all.jar;path/to/net.sf.eclipsecs.core-6.1.jar" \
 > -checkstyle-metadata.properties-dir src \
 > -checkstyle-metadata.xml-dir src \
 > -messages.properties-dir src \
 > <span style="color:red">-mediawiki-dir mediawiki</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...
 $

This will generate:

'''File "mediawiki/com.pany ColorCheck.mw":'''
 <!-- This file was generated by the CS doclet; see http://cs-contrib.unkrig.de -->
 <span style="color:red">A completely useless check which merely prints a (localizable) message each time it encounters an annotation.</span>
 
 == Properties ==
 
 Default values appear &lt;u>underlined&lt;/u>.
 
 &lt;dl>
 &lt;dt><span style="color:red">color</span> = "&lt;i><span style="color:red">String</span>&lt;/i>" (optional; default value is "<span style="color:red">Yellow</span>")
 &lt;dd><span style="color:red">A completely useless check parameter.</span>
 &lt;/dl>

Upload this text to a MediaWiki repository, and you'll see:

[[File:screenshot_mediawiki.jpg]]

And you're done!

== Summary ==

Before, you had to write one Java file and four more or less redundant metadata files per check; now you merely have to throw in a few annotations and doc comments and generate all four metadata files from the source code