Cs-doclet: Difference between revisions

From unkrig.de
Jump to navigation Jump to search
(Created page with "Cs-doclet is a [http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/ doclet] that generates the metadata files for CheckStyle checks and filters from 'doc tags' in t...")
 
No edit summary
Line 1: Line 1:
Cs-doclet is a [http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/ doclet] that generates the metadata files for CheckStyle checks and filters from 'doc tags' in the source files.
Cs-doclet is a [http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/ doclet] that generates the metadata files for CheckStyle checks and filters from 'doc tags' in the source files.


This tool is useful for developers of [http://checkstyle.sourceforge.net/ CheckStyle] checks and filters, and their integration in [eclipse-cs.sourceforge.net/ eclipse-cs].
This tool is useful for developers of [http://checkstyle.sourceforge.net/ CheckStyle] checks and filters, and their integration in [http://eclipse-cs.sourceforge.net/ eclipse-cs].


== Extending CheckStyle ==
== Extending CheckStyle ==

Revision as of 13:47, 29 December 2014

Cs-doclet is a doclet that generates the metadata files for CheckStyle checks and filters from 'doc tags' in the source files.

This tool is useful for developers of CheckStyle checks and filters, and their integration in eclipse-cs.

Extending CheckStyle

CheckStyle comes with an API to extend the standard set of checks and filters. This API supports internationalization be means of "messages.properties" files:

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); }
}

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}

File "src/com/pany/cs/checks/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>

File "checkstyle-config.xml":

<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>
$ 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:33:5: warning: The color is 'blue'
C:\dev\EclipseWS\de.unkrig.cs-contrib\foo\src\com\pany\cs\checks\ColorCheck.java:36:5: warning: The color is 'blue'
Audit done.
$

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 {

    /** @cs-message The color is {0} */
    public static final String MESSAGE_KEY_THE_COLOR_IS = "theColorIs";

    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); }
}

To generate the "messages.properties" file, you'd run JAVADOC with the cs-doclet and the "-messages.properties-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
> -messages.properties-dir src
> -sourcepath src
> -classpath ../net.sf.checkstyle-6.1/checkstyle-6.1/checkstyle-6.1-all.jar
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 "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 documentation of the check and its property "color" is where it belongs: 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;

/**
 * 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
 */
public
class ColorCheck extends Check {

    /** @cs-message The color is {0} */
    public static final String MESSAGE_KEY_THE_COLOR_IS = "theColorIs";

    /**
     * A completely useless check parameter.
     *
     * @cs-property-name          color
     * @cs-property-datatype      String
     * @cs-property-default-value Yellow
     */
    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
> -checkstyle-metadata.properties-dir src
> -checkstyle-metadata.xml-dir src
> -messages.properties-dir src
> -sourcepath src
> -classpath ../net.sf.checkstyle-6.1/checkstyle-6.1/checkstyle-6.1-all.jar
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>



    <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
> -mediawiki-dir mediawiki
> -sourcepath src
> -classpath ../net.sf.checkstyle-6.1/checkstyle-6.1/checkstyle-6.1-all.jar
Loading source files for package com.pany.cs.checks...
Constructing Javadoc information...
$

This will generate:

File "mediawiki/com.pany.cs.ColorCheck.mw":

A completely useless check which merely prints a (localizable) message each time it encounters an annotation.
== Properties ==

Default values appear underlined.

color = "String" (optional; default value is Yellow)
A completely useless check parameter.

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

Screenshot mediawiki.jpg