From d4791bca408a40bf3d91bd2c46fb53287d6ff700 Mon Sep 17 00:00:00 2001 From: liscju Date: Wed, 10 Feb 2016 18:24:39 +0100 Subject: [PATCH] Issue #2889: Adds skipNoJavadoc option to MissingDeprecated check --- .../annotation/MissingDeprecatedCheck.java | 37 +++++++++++++++++- .../MissingDeprecatedCheckTest.java | 13 +++++++ .../InputMissingDeprecatedSkipNoJavadoc.java | 27 +++++++++++++ src/xdocs/config_annotation.xml | 38 ++++++++++++++++++- 4 files changed, 113 insertions(+), 2 deletions(-) create mode 100644 src/test/resources/com/puppycrawl/tools/checkstyle/checks/annotation/InputMissingDeprecatedSkipNoJavadoc.java diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/annotation/MissingDeprecatedCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/annotation/MissingDeprecatedCheck.java index 76dfc472b..0701a37b9 100644 --- a/src/main/java/com/puppycrawl/tools/checkstyle/checks/annotation/MissingDeprecatedCheck.java +++ b/src/main/java/com/puppycrawl/tools/checkstyle/checks/annotation/MissingDeprecatedCheck.java @@ -70,6 +70,30 @@ import com.puppycrawl.tools.checkstyle.utils.CommonUtils; * <module name="JavadocDeprecated"/> * * + *

+ * In addition you can configure this check with skipNoJavadoc + * option to allow it to ignore cases when JavaDoc is missing, + * but still warns when JavaDoc is present but either + * {@link Deprecated Deprecated} is missing from JavaDoc or + * {@link Deprecated Deprecated} is missing from the element. + * To configure this check to allow it use: + *

+ * + * 
   <property name="skipNoJavadoc" value="true" />
+ * + *

Examples of validating source code with skipNoJavadoc:

+ * + * 
+ * 
+ * {@literal @}deprecated
+ * public static final int MY_CONST = 123456; // no violation
+ *
+ * /** This javadoc is missing deprecated tag. */
+ * {@literal @}deprecated
+ * public static final int COUNTER = 10; // violation as javadoc exists
+ * 
+ *
+ * * @author Travis Schneeberger */ public final class MissingDeprecatedCheck extends AbstractCheck { @@ -116,6 +140,17 @@ public final class MissingDeprecatedCheck extends AbstractCheck { /** Multiline finished at next Javadoc. */ private static final String NEXT_TAG = "@"; + /** Is deprecated element valid without javadoc. */ + private boolean skipNoJavadoc; + + /** + * Set skipJavadoc value. + * @param skipNoJavadoc user's value of skipJavadoc + */ + public void setSkipNoJavadoc(boolean skipNoJavadoc) { + this.skipNoJavadoc = skipNoJavadoc; + } + @Override public int[] getDefaultTokens() { return getAcceptableTokens(); @@ -152,7 +187,7 @@ public final class MissingDeprecatedCheck extends AbstractCheck { final boolean containsJavadocTag = containsJavadocTag(javadoc); - if (containsAnnotation ^ containsJavadocTag) { + if (containsAnnotation ^ containsJavadocTag && !(skipNoJavadoc && javadoc == null)) { log(ast.getLineNo(), MSG_KEY_ANNOTATION_MISSING_DEPRECATED); } } diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/checks/annotation/MissingDeprecatedCheckTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/checks/annotation/MissingDeprecatedCheckTest.java index fda0cdeab..956b17ebb 100644 --- a/src/test/java/com/puppycrawl/tools/checkstyle/checks/annotation/MissingDeprecatedCheckTest.java +++ b/src/test/java/com/puppycrawl/tools/checkstyle/checks/annotation/MissingDeprecatedCheckTest.java @@ -169,4 +169,17 @@ public class MissingDeprecatedCheckTest extends BaseCheckTestSupport { verify(checkConfig, getPath("InputMissingDeprecated2.java"), expected); } + + @Test + public void testSkipNoJavadocOption() throws Exception { + final DefaultConfiguration checkConfig = createCheckConfig(MissingDeprecatedCheck.class); + checkConfig.addAttribute("skipNoJavadoc", "true"); + + final String[] expected = { + "10: " + getCheckMessage(MSG_KEY_ANNOTATION_MISSING_DEPRECATED), + "26: " + getCheckMessage(MSG_KEY_ANNOTATION_MISSING_DEPRECATED), + }; + + verify(checkConfig, getPath("InputMissingDeprecatedSkipNoJavadoc.java"), expected); + } } diff --git a/src/test/resources/com/puppycrawl/tools/checkstyle/checks/annotation/InputMissingDeprecatedSkipNoJavadoc.java b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/annotation/InputMissingDeprecatedSkipNoJavadoc.java new file mode 100644 index 000000000..971576a59 --- /dev/null +++ b/src/test/resources/com/puppycrawl/tools/checkstyle/checks/annotation/InputMissingDeprecatedSkipNoJavadoc.java @@ -0,0 +1,27 @@ +package com.puppycrawl.tools.checkstyle.checks.annotation; + +public class InputMissingDeprecatedSkipNoJavadoc { + @Deprecated + public static final int MY_CONST = 123456; + + /** + * Useless comment. + */ + @Deprecated + public static final int MY_CONST2 = 234567; + + /** + * Useless comment. + * + * @deprecated Not for public use. + */ + @Deprecated + public static final int MY_CONST3 = 345678; + + /** + * Useless comment. + * + * @deprecated Not for public use. + */ + public static final int MY_CONST4 = 345678; +} diff --git a/src/xdocs/config_annotation.xml b/src/xdocs/config_annotation.xml index e97e40545..0176a311c 100644 --- a/src/xdocs/config_annotation.xml +++ b/src/xdocs/config_annotation.xml @@ -313,9 +313,45 @@ public String getNameIfPresent() { ... } present and the @deprecated Javadoc tag is present when either is present.

+ + + + + + + + + + + + + + +
namedescriptiontypedefault value
skipNoJavadocWhen this property is set to true check ignore cases + when JavaDoc is missing, but still warns when JavaDoc is + present but either @deprecated is missing from JavaDoc or + @deprecated is missing from the element. + booleanfalse
+

To configure the check:

- <module name="MissingDeprecated"/> + +<module name="MissingDeprecated"/> + +

In addition you can configure this check with skipNoJavadoc option:

+ +<module name="MissingDeprecated"> + <property name="skipNoJavadoc" value="true" /> +</module> + +

Examples of validating source code with skipNoJavadoc:

+ +@deprecated +public static final int MY_CONST = 123456; // no violation + +/** This javadoc is missing deprecated tag. */ +@deprecated +public static final int COUNTER = 10; // violation as javadoc exists