diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheck.java index 487efa58bf0..0c05339593b 100644 --- a/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheck.java +++ b/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheck.java @@ -19,6 +19,7 @@ package com.puppycrawl.tools.checkstyle.checks.javadoc; +import java.util.Arrays; import java.util.regex.Pattern; import com.puppycrawl.tools.checkstyle.StatelessCheck; @@ -28,6 +29,7 @@ import com.puppycrawl.tools.checkstyle.api.Scope; import com.puppycrawl.tools.checkstyle.api.TextBlock; import com.puppycrawl.tools.checkstyle.api.TokenTypes; +import com.puppycrawl.tools.checkstyle.checks.naming.AccessModifierOption; import com.puppycrawl.tools.checkstyle.utils.ScopeUtil; /** @@ -36,15 +38,10 @@ *
*- * By default, this setting will report a violation if - * there is no javadoc for any scope member. + * By default, this setting will report a violation + * if there is no javadoc for a member with any access modifier. *
** public class Test { @@ -84,40 +81,16 @@ * } **
- * To configure the check for {@code public} scope: - *
- *- * <module name="JavadocVariable"> - * <property name="scope" value="public"/> - * </module> - *- *
This setting will report a violation if there is no javadoc for {@code public} member.
- *- * public class Test { - * private int a; // OK - * - * /** - * * Some description here - * */ - * private int b; // OK - * protected int c; // OK - * public int d; // violation, missing javadoc for public member - * /*package*/ int e; // OK - * } - *- *
- * To configure the check for members which are in {@code private}, - * but not in {@code protected} scope: + * To configure the check for {@code package} and {@code private} variables: *
** <module name="JavadocVariable"> - * <property name="scope" value="private"/> - * <property name="excludeScope" value="protected"/> + * <property name="accessModifiers" value="package,private"/> * </module> **
- * This setting will report a violation if there is no javadoc for {@code private} - * member and ignores {@code protected} member. + * This setting will report a violation if there is no javadoc for {@code package} + * or {@code private} members. *
** public class Test { @@ -141,8 +114,8 @@ * </module> **
- * This setting will report a violation if there is no javadoc for any scope - * member and ignores members with name {@code log} or {@code logger}. + * This setting will report a violation if there is no javadoc for a + * member with any scope and ignores members with name {@code log} or {@code logger}. *
** public class Test { @@ -183,31 +156,25 @@ public class JavadocVariableCheck */ public static final String MSG_JAVADOC_MISSING = "javadoc.missing"; - /** Specify the visibility scope where Javadoc comments are checked. */ - private Scope scope = Scope.PRIVATE; - - /** Specify the visibility scope where Javadoc comments are not checked. */ - private Scope excludeScope; + /** Specify the access modifiers where Javadoc comments are checked. */ + private AccessModifierOption[] accessModifiers = { + AccessModifierOption.PUBLIC, + AccessModifierOption.PROTECTED, + AccessModifierOption.PACKAGE, + AccessModifierOption.PRIVATE, + }; /** Specify the regexp to define variable names to ignore. */ private Pattern ignoreNamePattern; /** - * Setter to specify the visibility scope where Javadoc comments are checked. - * - * @param scope a scope. - */ - public void setScope(Scope scope) { - this.scope = scope; - } - - /** - * Setter to specify the visibility scope where Javadoc comments are not checked. + * Setter to specify the access modifiers where Javadoc comments are checked. * - * @param excludeScope a scope. + * @param accessModifiers access modifiers of variables which should be checked. */ - public void setExcludeScope(Scope excludeScope) { - this.excludeScope = excludeScope; + public void setAccessModifiers(AccessModifierOption... accessModifiers) { + this.accessModifiers = + Arrays.copyOf(accessModifiers, accessModifiers.length); } /** @@ -285,12 +252,56 @@ private boolean shouldCheck(final DetailAST ast) { } final Scope surroundingScope = ScopeUtil.getSurroundingScope(ast); - result = customScope.isIn(scope) && surroundingScope.isIn(scope) - && (excludeScope == null - || !customScope.isIn(excludeScope) - || !surroundingScope.isIn(excludeScope)); + + final Scope effectiveScope; + if (surroundingScope.isIn(customScope)) { + effectiveScope = customScope; + } + else { + effectiveScope = surroundingScope; + } + result = matchAccessModifiers(toAccessModifier(effectiveScope)); } return result; } + /** + * Checks whether a variable has the correct access modifier to be checked. + * + * @param accessModifier the access modifier of the variable. + * @return whether the variable matches the expected access modifier. + */ + private boolean matchAccessModifiers(final AccessModifierOption accessModifier) { + return Arrays.stream(accessModifiers) + .anyMatch(modifier -> modifier == accessModifier); + } + + /** + * Converts a {@link Scope} to {@link AccessModifierOption}. {@code Scope.NOTHING} and {@code + * Scope.ANONINNER} are converted to {@code AccessModifierOption.PUBLIC}. + * + * @param scope Scope to be converted. + * @return the corresponding AccessModifierOption. + */ + private static AccessModifierOption toAccessModifier(Scope scope) { + final AccessModifierOption accessModifier; + switch (scope) { + case PROTECTED: + accessModifier = AccessModifierOption.PROTECTED; + break; + case PACKAGE: + accessModifier = AccessModifierOption.PACKAGE; + break; + case PRIVATE: + accessModifier = AccessModifierOption.PRIVATE; + break; + case NOTHING: + case ANONINNER: + case PUBLIC: + default: + accessModifier = AccessModifierOption.PUBLIC; + } + return accessModifier; + } + } diff --git a/src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/javadoc/JavadocVariableCheck.xml b/src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/javadoc/JavadocVariableCheck.xml index aea982226cd..a5e7ea0806f 100644 --- a/src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/javadoc/JavadocVariableCheck.xml +++ b/src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/javadoc/JavadocVariableCheck.xml @@ -8,14 +8,11 @@ Checks that a variable has a Javadoc comment. Ignores {@code serialVersionUID} fields. </p>- - -Specify the visibility scope where Javadoc comments are checked. -- Specify the visibility scope where Javadoc - comments are not checked. ++ Specify the access modifiers where Javadoc comments are + checked. Specify the regexp to define variable names to ignore. diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheckTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheckTest.java index eaa58359809..c7ff458f2c6 100644 --- a/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheckTest.java +++ b/src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/JavadocVariableCheckTest.java @@ -26,8 +26,8 @@ import com.puppycrawl.tools.checkstyle.AbstractModuleTestSupport; import com.puppycrawl.tools.checkstyle.DefaultConfiguration; -import com.puppycrawl.tools.checkstyle.api.Scope; import com.puppycrawl.tools.checkstyle.api.TokenTypes; +import com.puppycrawl.tools.checkstyle.checks.naming.AccessModifierOption; import com.puppycrawl.tools.checkstyle.utils.CommonUtil; public class JavadocVariableCheckTest @@ -93,7 +93,7 @@ public void testAnother2() throws Exception { final DefaultConfiguration checkConfig = createModuleConfig(JavadocVariableCheck.class); - checkConfig.addAttribute("scope", Scope.PUBLIC.getName()); + checkConfig.addAttribute("accessModifiers", AccessModifierOption.PUBLIC.toString()); final String[] expected = CommonUtil.EMPTY_STRING_ARRAY; verify(checkConfig, getPath("InputJavadocVariableInner2.java"), expected); } @@ -120,7 +120,7 @@ public void testAnother4() throws Exception { final DefaultConfiguration checkConfig = createModuleConfig(JavadocVariableCheck.class); - checkConfig.addAttribute("scope", Scope.PUBLIC.getName()); + checkConfig.addAttribute("accessModifiers", AccessModifierOption.PUBLIC.toString()); final String[] expected = { "46:5: " + getCheckMessage(MSG_JAVADOC_MISSING), }; @@ -128,7 +128,7 @@ public void testAnother4() } @Test - public void testScopes() throws Exception { + public void testAccessModifiersAll() throws Exception { final DefaultConfiguration checkConfig = createModuleConfig(JavadocVariableCheck.class); final String[] expected = { @@ -176,10 +176,13 @@ public void testScopes() throws Exception { } @Test - public void testScopes2() throws Exception { + public void testAccessModifiersPublicProtected() throws Exception { final DefaultConfiguration checkConfig = createModuleConfig(JavadocVariableCheck.class); - checkConfig.addAttribute("scope", Scope.PROTECTED.getName()); + checkConfig.addAttribute( + "accessModifiers", + AccessModifierOption.PROTECTED.name() + "," + AccessModifierOption.PUBLIC.name() + ); final String[] expected = { "10:5: " + getCheckMessage(MSG_JAVADOC_MISSING), "11:5: " + getCheckMessage(MSG_JAVADOC_MISSING), @@ -192,11 +195,13 @@ public void testScopes2() throws Exception { } @Test - public void testExcludeScope() throws Exception { + public void testAccessModifiersPrivatePackage() throws Exception { final DefaultConfiguration checkConfig = createModuleConfig(JavadocVariableCheck.class); - checkConfig.addAttribute("scope", Scope.PRIVATE.getName()); - checkConfig.addAttribute("excludeScope", Scope.PROTECTED.getName()); + checkConfig.addAttribute( + "accessModifiers", + AccessModifierOption.PRIVATE.name() + "," + AccessModifierOption.PACKAGE.name() + ); final String[] expected = { "11:5: " + getCheckMessage(MSG_JAVADOC_MISSING), "12:5: " + getCheckMessage(MSG_JAVADOC_MISSING), diff --git a/src/xdocs/config_javadoc.xml b/src/xdocs/config_javadoc.xml index 99817a11887..5b0ffa6c963 100644 --- a/src/xdocs/config_javadoc.xml +++ b/src/xdocs/config_javadoc.xml @@ -2279,19 +2279,14 @@ class DatabaseConfiguration {}since - -scope -Specify the visibility scope where Javadoc comments are checked. -Scope -+ private
accessModifiers +Specify the access modifiers where Javadoc comments are checked. +AccessModifierOption[] + + +public, protected, package, private
3.0 - excludeScope -Specify the visibility scope where Javadoc comments are not checked. -Scope -- null
3.4 -ignoreNamePattern Specify the regexp to define variable names to ignore. @@ -2325,7 +2320,7 @@ class DatabaseConfiguration {}By default, this setting will report a violation if - there is no javadoc for any scope member. + there is no javadoc for a member with any access modifier.
- To configure the check for
- - -public
- scope: -- This setting will report a violation if there - is no javadoc for
- - -public
member. -- To configure the check for members which are in
private
, but not in -protected
scope: + To configure the check forpackage
andprivate
+ variables:This setting will report a violation if there is no - javadoc for
private
member and - ignoresprotected
member. + javadoc forpackage
orprivate
members.This setting will report a violation if there is no - javadoc for any scope member and ignores members with + javadoc for a member with any scope and ignores members with name
log
orlogger
.