Editing
Cs-doclet
Jump to navigation
Jump to search
Warning:
You are not logged in. Your IP address will be publicly visible if you make any edits. If you
log in
or
create an account
, your edits will be attributed to your username, along with other benefits.
Anti-spam check. Do
not
fill this in!
<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 [http://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDJGIJB doc tags] in the source code of your checks and filters. This doclet is useful only for authors of CheckStyle extensions, like [[Cs-contrib.unkrig.de|cs-contrib]]. == 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-doclet.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-doclet.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> <!-- This file was generated by the CS doclet; see http://cs-doclet.unkrig.de/ --> <!-- 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> == 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! == 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 == Source code == The source code for the plug-in is here: https://github.com/aunkrig/doclet-cs https://github.com/aunkrig/doclet-cs-annotation
Summary:
Please note that all contributions to unkrig.de may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see
Unkrig.de:Copyrights
for details).
Do not submit copyrighted work without permission!
Cancel
Editing help
(opens in new window)
Navigation menu
Personal tools
Not logged in
Talk
Contributions
Create account
Log in
Namespaces
Page
Discussion
English
Views
Read
Edit
View history
More
Search
Navigation
Main page
Recent changes
Random page
Help
Tools
What links here
Related changes
Special pages
Page information