Editing Cs-doclet

== 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 'doc tags' in the source code of your checks and filters.

== Intended audience ==

This tool is useful for 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 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.cs.checks.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 bin;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 doc tags 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">/** @cs-message The color is ''{0}'' */
     public 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.cs.ColorCheck ---------------
 theColorIs = The color is ''{0}''

Now 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="%com.pany.cs.checks.ColorCheck.name"
         >
             <alternative-name internal-name="com.pany.cs.checks.ColorCheck" />
             <description>%com.pany.cs.checks.ColorCheck.desc</description>
 
             <property-metadata
                 name="color"
                 datatype="String"
                 default-value="Yellow"
             >
                 <description>%com.pany.cs.checks.ColorCheck.color</description>
             </property-metadata>
             <message-key key="theColorIs" />
         </rule-metadata>
     </rule-group-metadata>
 </checkstyle-metadata>

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

Tedious, isn't it? Well, you can tell cs-doclet to also generate ''these'' files from 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;
 
 <span style="color:red">/**
  * A completely useless check which merely prints a (localizable) message each time it encounters an annotation.
  *
  * @cs-rule-group         %Whitespace.group
  * @cs-rule-name          com.pany.cs.ColorCheck
  * @cs-rule-parent        TreeWalker
  */</span>
 public
 class ColorCheck extends Check {
 
     /** @cs-message The color is ''{0}'' */
     public static final String MESSAGE_KEY_THE_COLOR_IS = "theColorIs";
 
     <span style="color:red">/**
      * A completely useless check parameter.
      *
      * @cs-property-name          color
      * @cs-property-datatype      String
      * @cs-property-default-value Yellow
      */</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, 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:
 Whitespace.group = Whitespace
 
 # Custom checks, in alphabetical order.
 
 # --------------- com.pany.cs.ColorCheck ---------------
 
 com.pany.cs.checks.ColorCheck.name = com.pany.cs.ColorCheck
 com.pany.cs.checks.ColorCheck.desc =\
     A completely useless check which merely prints a (localizable) message each time it encounters an annotation.
 com.pany.cs.checks.ColorCheck.color                                  = A completely useless check parameter.

'''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="%Whitespace.group" priority="999">
         <rule-metadata
             internal-name="com.pany.cs.checks.ColorCheck"
             parent="TreeWalker"
             name="%com.pany.cs.checks.ColorCheck.name"
         >
             <alternative-name internal-name="com.pany.cs.checks.ColorCheck" />
             <description>%com.pany.cs.checks.ColorCheck.desc</description>
 
             <property-metadata
                 name="color"
                 datatype="String"
                 default-value="Yellow"
             >
                 <description>%com.pany.cs.checks.ColorCheck.color</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 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.cs.ColorCheck.mw":'''
 <!-- This file was generated by the CS doclet; see http://cs-contrib.unkrig.de -->
 A completely useless check which merely prints a (localizable) message each time it encounters an annotation.
 
 == Properties ==
 
 Default values appear <u>underlined</u>.
 
 <dl>
 <dt>color = "<i>String</i>" (optional; default value is Yellow)
 <dd>A completely useless check parameter.
 </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 doc tags and generate all four metadata files from the source code