diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AtclauseOrderCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AtclauseOrderCheck.java new file mode 100644 index 000000000..065ed7666 --- /dev/null +++ b/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AtclauseOrderCheck.java @@ -0,0 +1,176 @@ +//////////////////////////////////////////////////////////////////////////////// +// checkstyle: Checks Java source code for adherence to a set of rules. +// Copyright (C) 2001-2014 Oliver Burn +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2.1 of the License, or (at your option) any later version. +// +// This library is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +//////////////////////////////////////////////////////////////////////////////// +package com.puppycrawl.tools.checkstyle.checks.javadoc; + +import java.util.ArrayList; +import java.util.Arrays; +import java.util.List; + +import com.puppycrawl.tools.checkstyle.api.DetailAST; +import com.puppycrawl.tools.checkstyle.api.DetailNode; +import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes; +import com.puppycrawl.tools.checkstyle.api.TokenTypes; + +/** + *

+ * Checks the order of at-clauses. + *

+ * + *

+ * The check allows to configure itself by using the following properties: + *

+ * + *

+ * Default configuration: + *

+ * 
+ * <module name="AtclauseOrderCheck">
+ *     <property name="tagOrder" value="@author, @version, @param,
+ *     @return, @throws, @exception, @see, @since, @serial,
+ *     @serialField, @serialData, @deprecated"/>
+ *     <property name="target" value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF,
+ *     METHOD_DEF, CTOR_DEF, VARIABLE_DEF"/>
+ * </module>
+ *
+ * + * @author max + * + */ +public class AtclauseOrderCheck extends AbstractJavadocCheck +{ + + /** + * Some javadoc. + */ + private static final String[] DEFAULT_ORDER = { + "@author", "@version", + "@param", "@return", + "@throws", "@exception", + "@see", "@since", + "@serial", "@serialField", + "@serialData", "@deprecated", + }; + + /** + * Some javadoc. + */ + private List mTarget = Arrays.asList( + TokenTypes.CLASS_DEF, + TokenTypes.INTERFACE_DEF, + TokenTypes.ENUM_DEF, + TokenTypes.METHOD_DEF, + TokenTypes.CTOR_DEF, + TokenTypes.VARIABLE_DEF + ); + + /** + * Some javadoc. + */ + private List mTagOrder = Arrays.asList(DEFAULT_ORDER); + + /** + * Some javadoc. + * @param aTarget Some javadoc. + */ + public void setTarget(String aTarget) + { + final List customTarget = new ArrayList(); + for (String type : aTarget.split(", ")) { + customTarget.add(TokenTypes.getTokenId(type)); + } + mTarget = customTarget; + } + + /** + * Some javadoc. + * @param aOrder Some javadoc. + */ + public void setTagOrder(String aOrder) + { + final List customOrder = new ArrayList(); + for (String type : aOrder.split(", ")) { + customOrder.add(type); + } + mTagOrder = customOrder; + } + + @Override + public int[] getDefaultJavadocTokens() + { + return new int[] { + JavadocTokenTypes.JAVADOC, + }; + } + + @Override + public void visitJavadocToken(DetailNode aAst) + { + final int parentType = getParentType(getBlockCommentAst()); + + if (mTarget.contains(parentType)) { + checkOrderInTagSection(aAst); + } + } + + /** + * Some javadoc. + * @param aJavadoc Some javadoc. + */ + private void checkOrderInTagSection(DetailNode aJavadoc) + { + int indexOrderOfPreviousTag = 0; + int indexOrderOfCurrentTag = 0; + + for (DetailNode node : aJavadoc.getChildren()) { + if (node.getType() == JavadocTokenTypes.JAVADOC_TAG) { + final String tagText = JavadocUtils.getFirstChild(node).getText(); + indexOrderOfCurrentTag = mTagOrder.indexOf(tagText); + + if (mTagOrder.contains(tagText) + && indexOrderOfCurrentTag < indexOrderOfPreviousTag) + { + log(node.getLineNumber(), "at.clause.order", mTagOrder.toString()); + } + indexOrderOfPreviousTag = indexOrderOfCurrentTag; + } + } + } + + /** + * Some javadoc. + * @param aCommentBlock Some javadoc. + * @return Some javadoc. + */ + private int getParentType(DetailAST aCommentBlock) + { + final DetailAST parentNode = aCommentBlock.getParent(); + int type = parentNode.getType(); + if (type == TokenTypes.TYPE || type == TokenTypes.MODIFIERS) { + type = parentNode.getParent().getType(); + } + return type; + } +} diff --git a/src/main/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties b/src/main/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties index 731aad668..62d6f6b8c 100644 --- a/src/main/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties +++ b/src/main/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties @@ -35,3 +35,5 @@ tag.continuation.indent=Line continuation have incorrect indentation level, expe summary.javaDoc=Forbidden summary fragment. summary.first.sentence=First sentence should be present. +at.clause.order=At-clauses have to appear in the order ''{0}''. + diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AtclauseOrderCheckTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AtclauseOrderCheckTest.java new file mode 100644 index 000000000..5d9f60813 --- /dev/null +++ b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AtclauseOrderCheckTest.java @@ -0,0 +1,100 @@ +//////////////////////////////////////////////////////////////////////////////// +// checkstyle: Checks Java source code for adherence to a set of rules. +// Copyright (C) 2001-2014 Oliver Burn +// +// This library is free software; you can redistribute it and/or +// modify it under the terms of the GNU Lesser General Public +// License as published by the Free Software Foundation; either +// version 2.1 of the License, or (at your option) any later version. +// +// This library is distributed in the hope that it will be useful, +// but WITHOUT ANY WARRANTY; without even the implied warranty of +// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +// Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public +// License along with this library; if not, write to the Free Software +// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA +//////////////////////////////////////////////////////////////////////////////// +package com.puppycrawl.tools.checkstyle.checks.javadoc; + +import com.puppycrawl.tools.checkstyle.BaseCheckTestSupport; +import com.puppycrawl.tools.checkstyle.DefaultConfiguration; +import org.junit.Test; + +public class AtclauseOrderCheckTest extends BaseCheckTestSupport +{ + + @Test + public void testCorrect() throws Exception + { + DefaultConfiguration checkConfig = createCheckConfig(AtclauseOrderCheck.class); + final String[] expected = {}; + + verify(checkConfig, getPath("javadoc/InputCorrectAtClauseOrderCheck.java"), expected); + } + + @Test + public void testIncorrect() throws Exception + { + final String tagOrder = "'[@author, @version, @param, @return, @throws, @exception, @see," + + " @since, @serial, @serialField, @serialData, @deprecated]'."; + DefaultConfiguration checkConfig = createCheckConfig(AtclauseOrderCheck.class); + final String[] expected = { + "9: At-clauses have to appear in the order " + tagOrder, + "11: At-clauses have to appear in the order " + tagOrder, + "12: At-clauses have to appear in the order " + tagOrder, + "40: At-clauses have to appear in the order " + tagOrder, + "50: At-clauses have to appear in the order " + tagOrder, + "51: At-clauses have to appear in the order " + tagOrder, + "62: At-clauses have to appear in the order " + tagOrder, + "69: At-clauses have to appear in the order " + tagOrder, + "86: At-clauses have to appear in the order " + tagOrder, + "87: At-clauses have to appear in the order " + tagOrder, + "99: At-clauses have to appear in the order " + tagOrder, + "101: At-clauses have to appear in the order " + tagOrder, + "115: At-clauses have to appear in the order " + tagOrder, + "123: At-clauses have to appear in the order " + tagOrder, + "134: At-clauses have to appear in the order " + tagOrder, + "135: At-clauses have to appear in the order " + tagOrder, + "145: At-clauses have to appear in the order " + tagOrder, + "153: At-clauses have to appear in the order " + tagOrder, + "161: At-clauses have to appear in the order " + tagOrder, + "172: At-clauses have to appear in the order " + tagOrder, + "183: At-clauses have to appear in the order " + tagOrder, + "185: At-clauses have to appear in the order " + tagOrder, + "199: At-clauses have to appear in the order " + tagOrder, + "202: At-clauses have to appear in the order " + tagOrder, + "213: At-clauses have to appear in the order " + tagOrder, + "223: At-clauses have to appear in the order " + tagOrder, + "230: At-clauses have to appear in the order " + tagOrder, + "237: At-clauses have to appear in the order " + tagOrder, + "247: At-clauses have to appear in the order " + tagOrder, + "248: At-clauses have to appear in the order " + tagOrder, + "259: At-clauses have to appear in the order " + tagOrder, + "261: At-clauses have to appear in the order " + tagOrder, + "275: At-clauses have to appear in the order " + tagOrder, + "277: At-clauses have to appear in the order " + tagOrder, + "278: At-clauses have to appear in the order " + tagOrder, + "288: At-clauses have to appear in the order " + tagOrder, + }; + verify(checkConfig, getPath("javadoc/InputIncorrectAtClauseOrderCheck.java"), expected); + } + + @Test + public void testIncorrectCustom() throws Exception + { + final String tagOrder = "'[@author, @version, @param, @return, @throws, @exception, @see," + + " @since, @serial, @serialField, @serialData, @deprecated]'."; + DefaultConfiguration checkConfig = createCheckConfig(AtclauseOrderCheck.class); + checkConfig.addAttribute("target", "CLASS_DEF"); + + final String[] expected = { + "9: At-clauses have to appear in the order " + tagOrder, + "11: At-clauses have to appear in the order " + tagOrder, + "12: At-clauses have to appear in the order " + tagOrder, + "115: At-clauses have to appear in the order " + tagOrder, + }; + verify(checkConfig, getPath("javadoc/InputIncorrectAtClauseOrderCheck.java"), expected); + } +} diff --git a/src/test/resources/com/puppycrawl/tools/checkstyle/javadoc/InputCorrectAtClauseOrderCheck.java b/src/test/resources/com/puppycrawl/tools/checkstyle/javadoc/InputCorrectAtClauseOrderCheck.java new file mode 100644 index 000000000..95a0563ed --- /dev/null +++ b/src/test/resources/com/puppycrawl/tools/checkstyle/javadoc/InputCorrectAtClauseOrderCheck.java @@ -0,0 +1,291 @@ +package com.puppycrawl.tools.checkstyle.javadoc; + +import java.io.Serializable; + +/** + * Some javadoc. + * + * @author max + * @version 1.0 + * @see Some javadoc. + * @since Some javadoc. + * @deprecated Some javadoc. + */ +class WithAnnotations implements Serializable +{ + + /** + * The client's first name. + * @serial + */ + private String fFirstName; + + /** + * The client's first name. + * @serial + */ + private String sSecondName; + + /** + * The client's first name. + * @serialField + */ + private String tThirdName; + + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @throws Exception Some text. + * @serialData Some javadoc. + * @deprecated Some text. + */ + String method(String aString) throws Exception + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @throws Exception Some text. + * @serialData Some javadoc. + */ + String method1(String aString) throws Exception + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @throws Exception Some text. + */ + void method2(String aString) throws Exception {} + + /** + * Some text. + * @throws Exception Some text. + * @deprecated Some text. + */ + void method3() throws Exception {} + + /** + * Some text. + * @return Some text. + * @throws Exception Some text. + */ + String method4() throws Exception + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @serialData Some javadoc. + * @deprecated Some text. + */ + String method5(String aString) + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @param aInt Some text. + * @param aBoolean Some text. + * @return Some text. + * @throws Exception Some text. + * @deprecated Some text. + */ + String method6(String aString, int aInt, boolean aBoolean) throws Exception + { + return "null"; + } + + /** + * + * @author max + * @version 1.0 + * @since Some javadoc. + */ + class InnerClassWithAnnotations + { + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @throws Exception Some text. + * @deprecated Some text. + */ + String method(String aString) throws Exception + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @throws Exception Some text. + * @serialData Some javadoc. + */ + String method1(String aString) throws Exception + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @throws Exception Some text. + */ + void method2(String aString) throws Exception {} + + /** + * Some text. + * @throws Exception Some text. + * @deprecated Some text. + */ + void method3() throws Exception {} + + /** + * Some text. + * @return Some text. + * @throws Exception Some text. + * @serialData Some javadoc. + */ + String method4() throws Exception + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @serialData Some javadoc. + * @deprecated Some text. + */ + String method5(String aString) + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @param aInt Some text. + * @param aBoolean Some text. + * @return Some text. + * @throws Exception Some text. + * @deprecated Some text. + */ + String method6(String aString, int aInt, boolean aBoolean) throws Exception + { + return "null"; + } + } + + InnerClassWithAnnotations anon = new InnerClassWithAnnotations() + { + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @throws Exception Some text. + * @deprecated Some text. + */ + String method(String aString) throws Exception + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @throws Exception Some text. + */ + String method1(String aString) throws Exception + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @throws Exception Some text. + * @serialData Some javadoc. + */ + void method2(String aString) throws Exception {} + + /** + * Some text. + * @throws Exception Some text. + * @deprecated Some text. + */ + void method3() throws Exception {} + + /** + * Some text. + * @return Some text. + * @throws Exception Some text. + */ + String method4() throws Exception + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @deprecated Some text. + */ + String method5(String aString) + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @param aInt Some text. + * @param aBoolean Some text. + * @return Some text. + * @throws Exception Some text. + * @deprecated Some text. + */ + String method6(String aString, int aInt, boolean aBoolean) throws Exception + { + return "null"; + } + }; +} + +/** + * Some javadoc. + * + * @author max + * @version 1.0 + * @see Some javadoc. + * @since Some javadoc. + * @deprecated Some javadoc. + */ +enum Foo {} + +/** + * Some javadoc. + * + * @author max + * @version 1.0 + * @see Some javadoc. + * @since Some javadoc. + * @deprecated Some javadoc. + */ +interface FooIn {} diff --git a/src/test/resources/com/puppycrawl/tools/checkstyle/javadoc/InputIncorrectAtClauseOrderCheck.java b/src/test/resources/com/puppycrawl/tools/checkstyle/javadoc/InputIncorrectAtClauseOrderCheck.java new file mode 100644 index 000000000..0b60a4741 --- /dev/null +++ b/src/test/resources/com/puppycrawl/tools/checkstyle/javadoc/InputIncorrectAtClauseOrderCheck.java @@ -0,0 +1,290 @@ +package com.puppycrawl.tools.checkstyle.javadoc; + +import java.io.Serializable; + +/** + * Some javadoc. + * + * @since Some javadoc. + * @version 1.0 //warn //warn + * @deprecated Some javadoc. + * @see Some javadoc. //warn + * @author max //warn + */ +class WithAnnotations implements Serializable +{ + /** + * The client's first name. + * @serial + */ + private String fFirstName; + + /** + * The client's first name. + * @serial + */ + private String sSecondName; + + /** + * The client's first name. + * @serialField + */ + private String tThirdName; + + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @serialData Some javadoc. + * @deprecated Some text. + * @throws Exception Some text. //warn + */ + String method(String aString) throws Exception + { + return "null"; + } + + /** + * Some text. + * @serialData Some javadoc. + * @return Some text. //warn + * @param aString Some text. //warn + * @throws Exception Some text. + */ + String method1(String aString) throws Exception + { + return "null"; + } + + /** + * Some text. + * @throws Exception Some text. + * @param aString Some text. //warn + */ + void method2(String aString) throws Exception {} + + /** + * Some text. + * @deprecated Some text. + * @throws Exception Some text. //warn + */ + void method3() throws Exception {} + + /** + * Some text. + * @return Some text. + * @throws Exception Some text. + */ + String method4() throws Exception + { + return "null"; + } + + /** + * Some text. + * @deprecated Some text. + * @return Some text. //warn + * @param aString Some text. //warn + */ + String method5(String aString) + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @serialData Some javadoc. + * @param aInt Some text. //warn + * @throws Exception Some text. + * @param aBoolean Some text. //warn + * @deprecated Some text. + */ + String method6(String aString, int aInt, boolean aBoolean) throws Exception + { + return "null"; + } + + /** + * Some javadoc. + * + * @version 1.0 + * @since Some javadoc. + * @serialData Some javadoc. + * @author max //warn + */ + class InnerClassWithAnnotations + { + /** + * Some text. + * @return Some text. + * @deprecated Some text. + * @param aString Some text. //warn + * @throws Exception Some text. + */ + String method(String aString) throws Exception + { + return "null"; + } + + /** + * Some text. + * @throws Exception Some text. + * @return Some text. //warn + * @param aString Some text. //warn + */ + String method1(String aString) throws Exception + { + return "null"; + } + + /** + * Some text. + * @serialData Some javadoc. + * @param aString Some text. //warn + * @throws Exception Some text. + */ + void method2(String aString) throws Exception {} + + /** + * Some text. + * @deprecated Some text. + * @throws Exception Some text. //warn + */ + void method3() throws Exception {} + + /** + * Some text. + * @throws Exception Some text. + * @serialData Some javadoc. + * @return Some text. //warn + */ + String method4() throws Exception + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @deprecated Some text. + * @return Some text. //warn + */ + String method5(String aString) + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @param aInt Some text. //warn + * @throws Exception Some text. + * @param aBoolean Some text. //warn + * @deprecated Some text. + */ + String method6(String aString, int aInt, boolean aBoolean) throws Exception + { + return "null"; + } + } + + InnerClassWithAnnotations anon = new InnerClassWithAnnotations() + { + /** + * Some text. + * @throws Exception Some text. + * @param aString Some text. //warn + * @serialData Some javadoc. + * @deprecated Some text. + * @return Some text. //warn + */ + String method(String aString) throws Exception + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @throws Exception Some text. + * @return Some text. //warn + */ + String method1(String aString) throws Exception + { + return "null"; + } + + /** + * Some text. + * @throws Exception Some text. + * @param aString Some text. //warn + */ + void method2(String aString) throws Exception {} + + /** + * Some text. + * @deprecated Some text. + * @throws Exception Some text. //warn + */ + void method3() throws Exception {} + + /** + * Some text. + * @throws Exception Some text. + * @return Some text. //warn + */ + String method4() throws Exception + { + return "null"; + } + + /** + * Some text. + * @deprecated Some text. + * @return Some text. //warn + * @param aString Some text. //warn + */ + String method5(String aString) + { + return "null"; + } + + /** + * Some text. + * @param aString Some text. + * @return Some text. + * @param aInt Some text. //warn + * @throws Exception Some text. + * @param aBoolean Some text. //warn + * @deprecated Some text. + */ + String method6(String aString, int aInt, boolean aBoolean) throws Exception + { + return "null"; + } + }; +} + +/** + * Some javadoc. + * + * @since Some javadoc. + * @version 1.0 //warn //warn + * @deprecated Some javadoc. + * @see Some javadoc. //warn + * @author max //warn + */ +enum Foo {} + +/** + * Some javadoc. + * + * @version 1.0 + * @since Some javadoc. + * @serialData Some javadoc. + * @author max //warn + */ +interface FooIn {} diff --git a/src/xdocs/availablechecks.xml b/src/xdocs/availablechecks.xml index 895d3cc5c..17b95710d 100644 --- a/src/xdocs/availablechecks.xml +++ b/src/xdocs/availablechecks.xml @@ -50,6 +50,10 @@ ArrayTypeStyle Checks the style of array type definitions. + + AtclauseOrder + Checks the order of at-clauses. + AvoidEscapedUnicodeCharacters Restrict using Unicode escapes. diff --git a/src/xdocs/config_javadoc.xml b/src/xdocs/config_javadoc.xml index d116dceb7..0037e505b 100644 --- a/src/xdocs/config_javadoc.xml +++ b/src/xdocs/config_javadoc.xml @@ -976,5 +976,83 @@ public boolean isSomething() +
+ +

+ Checks the order of at-clauses. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
namedescriptiontypedefault value
targetallows to specify targets to check at-clauses.subset of tokens CLASS_DEF, + INTERFACE_DEF, + ENUM_DEF, + METHOD_DEF, + CTOR_DEF, + VARIABLE_DEFAll of tokens
tagOrderallows to specify the order by tags.String@author, @version, @param, + @return, @throws, @exception, @see, @since, @serial, + @serialField, @serialData, @deprecated
tagSeveritySeverity level when tag is found and printedseverityinfo
+ + + +

+ Default configuration +

+ +<module name="AtclauseOrder"> + <property name="tagOrder" value="@author, @version, @param, + @return, @throws, @exception, @see, @since, @serial, + @serialField, @serialData, @deprecated"/> + <property name="target" value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF, + METHOD_DEF, CTOR_DEF, VARIABLE_DEF"/> +</module> + + + + +

+ com.puppycrawl.tools.checkstyle.checks +

+ + + +

+ TreeWalker +

+ +
+ + diff --git a/src/xdocs/google_style.xml b/src/xdocs/google_style.xml index ffc69dcd1..4ff6e6ef5 100644 --- a/src/xdocs/google_style.xml +++ b/src/xdocs/google_style.xml @@ -1246,7 +1246,10 @@ href="http://google-styleguide.googlecode.com/svn/trunk/javaguide.html#s7.1.3-javadoc-at-clauses">7.1.3 At-clauses - AtClauseOrder + + AtclauseOrder