Cs-doclet

From unkrig.de
(Difference between revisions)
Jump to: navigation, search
m (Abstract)
m (MediaWiki markup documentation)
 
Line 275: Line 275:
 
  </checkstyle-metadata>
 
  </checkstyle-metadata>
  
== MediaWiki markup documentation ==
+
== Javadoc-like 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:
+
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 "-d" command line option:
  
 
  $ javadoc \
 
  $ javadoc \
 
  > -doclet de.unkrig.doclet.cs.CsDoclet \
 
  > -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" \
 
  > -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 \
+
  > -d ./csdoc \
> -checkstyle-metadata.xml-dir src \
+
> -messages.properties-dir src \
+
> <span style="color:red">-mediawiki-dir mediawiki</span> \
+
 
  > -sourcepath src \
 
  > -sourcepath src \
 
  > -classpath ../net.sf.checkstyle-6.1/checkstyle-6.1/checkstyle-6.1-all.jar \
 
  > -classpath ../net.sf.checkstyle-6.1/checkstyle-6.1/checkstyle-6.1-all.jar \
Line 293: Line 290:
 
  $
 
  $
  
This will generate:
+
This will generate a Javadoc-like HTML documentation for all checks and filters that are declared in the given Java packages.
 
+
'''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!
 
And you're done!

Latest revision as of 23:09, 14 November 2017

Contents

[edit] Abstract

Cs-doclet is a JAVADOC doclet that generates the metadata files for CheckStyle and eclipse-cs from annotations and doc tags in the source code of your checks and filters.

[edit] Intended audience

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

[edit] Extending CheckStyle

CheckStyle comes with an API to 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 '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 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 {

    @Message("The color is {0}")
    private 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 \
> 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 ---------------
theColorIs = The color is {0}

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

[edit] 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;

/**
 * A completely useless check which merely prints a
 * (localizable) message each time it encounters an annotation.
 */
@Rule(
    group      = "%Whitespace.group",
    groupName  = "Whitespace",
    name       = "com.pany: ColorCheck",
    parent     = "TreeWalker"
)
public
class ColorCheck extends Check {

    @Message("The color is {0}")
    private static final String MESSAGE_KEY_THE_COLOR_IS = "theColorIs";

    /**
     * A completely useless check parameter.
     */
    @StringRuleProperty(defaultValue = DEFAULT_COLOR)
    public void
    setColor(String value) { this.color = value; }

    private String color = DEFAULT_COLOR;

    private static final String DEFAULT_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 \
> 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: ColorCheck ---------------

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.

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>

    <!-- This file was generated by the CS doclet; see http://cs-contrib.unkrig.de -->

    <!-- ColorCheck -->

    <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>

[edit] Javadoc-like 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 "-d" 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" \
> -d ./csdoc \
> -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 a Javadoc-like HTML documentation for all checks and filters that are declared in the given Java packages.

And you're done!

[edit] 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

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox