Editing Cs-doclet
Jump to navigation
Jump to search
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.
Latest revision | Your text | ||
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. | |||
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]. | |||
This tool is useful for | |||
== Extending CheckStyle == | == Extending CheckStyle == | ||
CheckStyle comes with an API to [http://checkstyle.sourceforge.net/writingchecks.html extend] | CheckStyle comes with an API to [http://checkstyle.sourceforge.net/writingchecks.html extend the standard set of checks] and [http://checkstyle.sourceforge.net/writingfilters.html filters]: | ||
'''File "src/com/pany/cs/checks/ColorCheck.java":''' | '''File "src/com/pany/cs/checks/ColorCheck.java":''' | ||
Line 36: | Line 28: | ||
} | } | ||
This API supports internationalization be means of "messages.properties" files: | |||
'''File "src/com/pany/cs/checks/messages.properties":''' | '''File "src/com/pany/cs/checks/messages.properties":''' | ||
Line 44: | Line 36: | ||
theColorIs = Die Farbe ist ''{0}'' | theColorIs = Die Farbe ist ''{0}'' | ||
Then you'd write a "CheckStyle configuration file" | |||
'''File "checkstyle-config.xml":''' | '''File "checkstyle-config.xml":''' | ||
Line 53: | Line 45: | ||
<property name="severity" value="warning" /> | <property name="severity" value="warning" /> | ||
<module name="TreeWalker"> | <module name="TreeWalker"> | ||
<module name="com.pany | <module name="com.pany.cs.checks.ColorCheck"> | ||
<property name="color" value="blue" /> | <property name="color" value="blue" /> | ||
</module> | </module> | ||
Line 62: | Line 54: | ||
$ javac -d bin src/com/pany/cs/checks/ColorCheck.java | $ javac -d bin src/com/pany/cs/checks/ColorCheck.java | ||
$ java -classpath | $ java -classpath bin;path/to/checkstyle-6.1-all.jar \ | ||
> com.puppycrawl.tools.checkstyle.Main \ | > com.puppycrawl.tools.checkstyle.Main \ | ||
> -c checkstyle-config.xml \ | > -c checkstyle-config.xml \ | ||
Line 76: | Line 68: | ||
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. | 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 | 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":''' | '''File "src/com/pany/cs/checks/MyCheck.java":''' | ||
Line 88: | Line 80: | ||
class ColorCheck extends Check { | class ColorCheck extends Check { | ||
<span style="color:red">@ | <span style="color:red">/** @cs-message The color is ''{0}'' */ | ||
public static final String MESSAGE_KEY_THE_COLOR_IS = "theColorIs";</span> | |||
public void | public void | ||
Line 105: | Line 97: | ||
$ javadoc \ | $ javadoc \ | ||
> <span style="color:red">-doclet de.unkrig.doclet.cs.CsDoclet</span> \ | > <span style="color:red">-doclet de.unkrig.doclet.cs.CsDoclet</span> \ | ||
> <span style="color:red">-docletpath | > <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> | > <span style="color:red">-messages.properties-dir src</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 | ||
> com.pany.cs.checks | > com.pany.cs.checks | ||
Loading source files for package com.pany.cs.checks... | Loading source files for package com.pany.cs.checks... | ||
Line 118: | Line 110: | ||
The generated "src/com/pany/cs/checks/messages.properties" file looks like this: | The generated "src/com/pany/cs/checks/messages.properties" file looks like this: | ||
# This file was generated by the CS doclet; see http://cs- | # This file was generated by the CS doclet; see http://cs-contrib.unkrig.de | ||
# Custom check messages, in alphabetical order. | # Custom check messages, in alphabetical order. | ||
# --------------- com.pany | # --------------- 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 == | == Integrating with eclipse-cs == | ||
Line 142: | Line 134: | ||
internal-name="com.pany.cs.checks.ColorCheck" | internal-name="com.pany.cs.checks.ColorCheck" | ||
parent="TreeWalker" | parent="TreeWalker" | ||
name="%ColorCheck.name" | name="%com.pany.cs.checks.ColorCheck.name" | ||
> | > | ||
<alternative-name internal-name="com.pany.cs.checks.ColorCheck" /> | <alternative-name internal-name="com.pany.cs.checks.ColorCheck" /> | ||
<description>%ColorCheck.desc</description> | <description>%com.pany.cs.checks.ColorCheck.desc</description> | ||
<property-metadata | <property-metadata | ||
Line 152: | Line 144: | ||
default-value="Yellow" | default-value="Yellow" | ||
> | > | ||
<description>%ColorCheck.color</description> | <description>%com.pany.cs.checks.ColorCheck.color</description> | ||
</property-metadata> | </property-metadata> | ||
<message-key key="theColorIs" /> | <message-key key="theColorIs" /> | ||
Line 161: | Line 153: | ||
'''File "checkstyle-metadata.properties":''' | '''File "checkstyle-metadata.properties":''' | ||
Whitespace.group = Whitespace | Whitespace.group = Whitespace | ||
ColorCheck.name = com.pany | com.pany.cs.checks.ColorCheck.name = com.pany.cs.ColorCheck | ||
ColorCheck.desc =\ | com.pany.cs.checks.ColorCheck.desc =\ | ||
A completely useless check which merely prints a (localizable) message each \ | A completely useless check which merely prints a (localizable) message each \ | ||
time it encounters an annotation. | time it encounters an annotation. | ||
ColorCheck.color = A completely useless check parameter. | 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 | 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/checks/MyCheck.java":''' | ||
Line 178: | Line 170: | ||
import com.puppycrawl.tools.checkstyle.api.TokenTypes; | 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 | public | ||
class ColorCheck extends Check { | 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 | public void | ||
setColor(String value) { this.color = value; } | setColor(String value) { this.color = value; } | ||
private String color = "Yellow"; | |||
private String color | |||
@Override public int[] | @Override public int[] | ||
Line 217: | Line 203: | ||
$ javadoc \ | $ javadoc \ | ||
> -doclet de.unkrig.doclet.cs.CsDoclet \ | > -doclet de.unkrig.doclet.cs.CsDoclet \ | ||
> -docletpath | > -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.properties-dir src</span> | ||
> <span style="color:red">-checkstyle-metadata.xml-dir src</span> | > <span style="color:red">-checkstyle-metadata.xml-dir src</span> | ||
> -messages.properties-dir src | > -messages.properties-dir src | ||
> -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 | ||
> com.pany.cs.checks | > com.pany.cs.checks | ||
Loading source files for package com.pany.cs.checks... | Loading source files for package com.pany.cs.checks... | ||
Line 231: | Line 217: | ||
'''File "src/com/pany/cs/checks/checkstyle-metadata.properties":''' | '''File "src/com/pany/cs/checks/checkstyle-metadata.properties":''' | ||
# This file was generated by the CS doclet; see http://cs- | # This file was generated by the CS doclet; see http://cs-contrib.unkrig.de. | ||
# Rule groups: | # Rule groups: | ||
Whitespace.group = Whitespace | |||
# Custom checks, in alphabetical order. | # 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":''' | '''File "src/com/pany/cs/checks/checkstyle-metadata.xml":''' | ||
Line 252: | Line 238: | ||
<checkstyle-metadata> | <checkstyle-metadata> | ||
<!-- This file was generated by the CS doclet; see http://cs- | <!-- This file was generated by the CS doclet; see http://cs-contrib.unkrig.de --> | ||
<!-- ColorCheck --> | <!-- ColorCheck --> | ||
<rule-group-metadata name=" | <rule-group-metadata name="%Whitespace.group" priority="999"> | ||
<rule-metadata | <rule-metadata | ||
internal-name=" | internal-name="com.pany.cs.checks.ColorCheck" | ||
parent=" | parent="TreeWalker" | ||
name=" | name="%com.pany.cs.checks.ColorCheck.name" | ||
> | > | ||
<alternative-name internal-name=" | <alternative-name internal-name="com.pany.cs.checks.ColorCheck" /> | ||
<description | <description>%com.pany.cs.checks.ColorCheck.desc</description> | ||
<property-metadata | <property-metadata | ||
name=" | name="color" | ||
datatype=" | datatype="String" | ||
default-value=" | default-value="Yellow" | ||
> | > | ||
<description | <description>%com.pany.cs.checks.ColorCheck.color</description> | ||
</property-metadata> | </property-metadata> | ||
<message-key key="theColorIs" /> | <message-key key="theColorIs" /> | ||
Line 277: | Line 263: | ||
</checkstyle-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 | 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 \ | $ javadoc \ | ||
> -doclet de.unkrig.doclet.cs.CsDoclet \ | > -doclet de.unkrig.doclet.cs.CsDoclet \ | ||
> -docletpath | > -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 | ||
> -sourcepath src | > -checkstyle-metadata.xml-dir src | ||
> -classpath ../net.sf.checkstyle-6.1/checkstyle-6.1/checkstyle-6.1-all.jar | > -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 | > com.pany.cs.checks | ||
Loading source files for package com.pany.cs.checks... | Loading source files for package com.pany.cs.checks... | ||
Line 292: | Line 281: | ||
$ | $ | ||
This will generate | 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 | |||