Issue sevntu-checkstyle#734: required text and formatting changes, ad…

…ditional Javadoc

sevntu-checks/sevntu-checks.xml

@@ -160,6 +160,7 @@
     <module name="com.github.sevntu.checkstyle.checks.coding.MoveVariableInsideIfCheck" />
     <module name="com.github.sevntu.checkstyle.checks.coding.RequireFailForTryCatchInJunitCheck" />
     <module name="com.github.sevntu.checkstyle.checks.coding.Jsr305AnnotationsCheck">
+      <!-- we ignore this Check only because we are not ready to follow it and refactor whole project for now-->
       <property name="severity" value="ignore"/>
       <property name="packages" value="com.github.sevntu.checkstyle.checks.naming,com.github.sevntu.checkstyle.checks.coding"/>
       <property name="excludePackages" value="com.github.sevntu.checkstyle.checks.sizes,com.github.sevntu.checkstyle.checks.design"/>

sevntu-checks/src/main/java/com/github/sevntu/checkstyle/checks/coding/Jsr305AnnotationsCheck.java

@@ -34,34 +34,53 @@
 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
 
 /**
- * Jsr305AnnotationsCheck - a check to enforce use of nullness anotations.
- * The standalone version of this plugin resides under
- * <a href="https://github.com/bjrke/JSR305CheckstylePlugin">
- * https://github.com/mbert/JSR305CheckstylePlugin</a>
  * <p>
- * Copyright (C) 2008 Marcus Thiesen (initial version) Copyright (C) 2008-2019 Jan Burkhardt
- * (maintainer)
- * <br>
- * Thanks to Mattias Nissler, Thorsten Ehlers, Fabian Loewner, Ole Langbehn for contributions.
+ * The <a href="https://jcp.org/en/jsr/detail?id=305">Jsr305 annotations</a> (annotations for
+ * software defect detection) contain a subset of "nullness" annotations that can be used to mark
+ * parameters as possibly null ({@code @Nullable}) or always non-null ({@code @Nonnull}), function
+ * return values as to be checked for null ({@code @CheckForNull}) or always non-null
+ * ({@code @Nonnull}) including defaults on class level ({@code @ParametersAreNonnullByDefault},
+ * {@code @ParametersAreNullableByDefault}, {@code @ReturnValuesAreNonnullByDefault}).
  * </p>
  * <p>
- * This check is activated by setting the package(s) to check:
- * <br>
- * packages = org.package1,com.package2
+ * Using these annotations a programmer can declare how the code is meant to behave, and static code
+ * analysis (like e.g. FindBugs) can be used to verify that this is actually true. Also these
+ * annotations help others understanding code more easily, e.g. if confrontend with an annotated
+ * interface the necessity for null checks can easily be deducted from the annotations.
  * </p>
  * <p>
- * Finetuning can be performed using the following settings:
- * <br>
- * Exclude some packages from checking:
- * <br>
- * excludePackages = org.package1.generated,com.package2.external
- * <br>
- * Allow overriding return values and/or parameters (useful for upgrading):
- * <br>
- * allowOverridingReturnValue = true
- * <br>
- * allowOverridingParameters = true
+ * The Jsr305AnnotationsCheck supports enforcing the following code style:
  * </p>
+ * <ul>
+ * <li>Every method declaration, implementation or lambda requires nullness annotations for all
+ * parameters and return values except for primitive types (because a void or an int can never be
+ * null anyway).</li>
+ * <li>The annotation can be made directly or applied through either inheritance from an already
+ * annotated class or a annotation for class-wide defaults.</li>
+ * <li>Annotations need to make sense. For instance, a class-scope annotation cannot be used for a
+ * method, and a method annotation cannot be used for a class.</li>
+ * <li>In overridden methods, the following rule applies (regardless of what was annotated in the
+ * parent method): For parameter definitions {@code @Nonnull} annotation is always illegal because
+ * being less "nullable" cannot be assumed for a parameter in an inherited method. Conversely
+ * {@code @Nullable} is always allowed. For return values it is the other way round:
+ * {@code @CheckForNull} is always illegal while {@code @Nonnull} is always legal.</li>
+ * </ul>
+ * <p>
+ * The following configuration properties are supported:
+ * </p>
+ * <dl>
+ * <dt>{@code packages = com.github.sevntu.pkg1,com.github.sevntu.pkg2}</dt>
+ * <dd>Activate this check for a list of parent packages and their children.</dd>
+ * <dt>{@code excludePackages = com.github.sevntu.pkg1.sub1,com.github.sevntu.pkg1.sub2}</dt>
+ * <dd>Set packages excluded from checking. This setting can be useful if under the parent package
+ * set with "packages" there are subpackages which should not be checked.</dd>
+ * <dt>{@code allowOverridingReturnValue = true}</dt>
+ * <dd>Annotating return values "@CheckForNull" in overridden methods is flagged as an error. When
+ * setting the this property to true, this error will be ignored (useful for upgrading).</dd>
+ * <dt>{@code allowOverridingParameters = true}</dt>
+ * <dd>Annotating parameters "@Nonnull" in overridden methods is flagged as an error. When setting
+ * this property to true, this error will be ignored (useful for upgrading).</dd>
+ * </dl>
  */
 public class Jsr305AnnotationsCheck extends AbstractCheck {
 

sevntu-checks/src/main/resources/com/github/sevntu/checkstyle/checks/coding/messages.properties

@@ -60,27 +60,27 @@ return.null.Boolean=Method declares to return Boolean and returns null.
 return.boolean.ternary=Returning explicit boolean from ternary operator.
 whitespace.before.array.initializer=Array initializer should have whitespace before.
 jsr305.illegal.class.level.annotation=@CheckForNull, @Nullable, @Nonnull and @CheckReturnValue are not allowed on class level. Use @ParametersAreNonnullByDefault, @ParametersAreNullableByDefault and @ReturnValuesAreNonnullByDefault.
-jsr305.contradicting.class.level.annotations=@ParametersAreNullableByDefault and @ParametersAreNonnullByDefault are not allowed together!
+jsr305.contradicting.class.level.annotations=@ParametersAreNullableByDefault and @ParametersAreNonnullByDefault are not allowed together.
 jsr305.param.definitions.with.check.annotation=Parameter definitions don't need checking, use @Nullable or @Nonnull.
-jsr305.param.definition.with.override.annotation=@Override is not allowed on parameter definition!
-jsr305.param.definition.with.nonnull.by.default.annotation=@ParametersAreNonnullByDefault is not allowed on parameter definition!
-jsr305.param.definition.with.nullable.by.default.annotation=@ParametersAreNullableByDefault is not allowed on parameter definition!
-jsr305.param.definition.with.return.values.default.annotation=@ReturnValuesAreNonnullByDefault is not allowed on parameter definition!
-jsr305.param.nonnull.and.nullable.annotation=@Nonnull and @Nullable are not allowed together!
-jsr305.primitives.with.nullness.annotation=Primitives must not have any nullness annotations!
-jsr305.overridden.definitions.with.increased.param.constraint=It is not allowed to increase nullness constraint for overriden method parameter definitions!
+jsr305.param.definition.with.override.annotation=@Override is not allowed on parameter definition.
+jsr305.param.definition.with.nonnull.by.default.annotation=@ParametersAreNonnullByDefault is not allowed on parameter definition.
+jsr305.param.definition.with.nullable.by.default.annotation=@ParametersAreNullableByDefault is not allowed on parameter definition.
+jsr305.param.definition.with.return.values.default.annotation=@ReturnValuesAreNonnullByDefault is not allowed on parameter definition.
+jsr305.param.nonnull.and.nullable.annotation=@Nonnull and @Nullable are not allowed together.
+jsr305.primitives.with.nullness.annotation=Primitives must not have any nullness annotations.
+jsr305.overridden.definitions.with.increased.param.constraint=It is not allowed to increase nullness constraint for overriden method parameter definitions.
 jsr305.redundant.nonnull.param.annotation=It is not necessary to annotate @Nonnull if you annotated the method or class with @ParametersAreNonnullByDefault.
 jsr305.redundant.nullable.param.annotation=It is not necessary to annotate @Nullable if you annoted the method or class with @ParametersAreNullableByDefault.
-jsr305.parameter.without.nullness.annotation=No nullness Annotation for parameter definition found!
-jsr305.return.value.with.nonnull.by.default.annotation=@ReturnValuesAreNonnullByDefault is not allowed on method return values!
-jsr305.return.value.with.nullable.annotation=@Nullable is not allowed on method return values!
-jsr305.contradicting.return.value.annotations=@Nonnull and @CheckForNull are not allowed together!
-jsr305.overridden.method.with.check.return.value.annotation=@CheckReturnValue is not allowed on overriden methods, annotate the interface or superclass!
-jsr305.redundant.nonnull.by.default.annotation=Redundant @ParametersAreNonnullByDefault, the class is annotated with the same annotation!
-jsr305.redundant.nullable.by.default.annotation=Redundant @ParametersAreNullableByDefault, the class is annotated with the same annotation!
-jsr305.void.with.check.return.value.annotation=There is nothing to check on void return methods, remove @CheckReturnValue!
+jsr305.parameter.without.nullness.annotation=No nullness Annotation for parameter definition found.
+jsr305.return.value.with.nonnull.by.default.annotation=@ReturnValuesAreNonnullByDefault is not allowed on method return values.
+jsr305.return.value.with.nullable.annotation=@Nullable is not allowed on method return values.
+jsr305.contradicting.return.value.annotations=@Nonnull and @CheckForNull are not allowed together.
+jsr305.overridden.method.with.check.return.value.annotation=@CheckReturnValue is not allowed on overriden methods, annotate the interface or superclass.
+jsr305.redundant.nonnull.by.default.annotation=Redundant @ParametersAreNonnullByDefault, the class is annotated with the same annotation.
+jsr305.redundant.nullable.by.default.annotation=Redundant @ParametersAreNullableByDefault, the class is annotated with the same annotation.
+jsr305.void.with.check.return.value.annotation=There is nothing to check on void return methods, remove @CheckReturnValue.
 jsr305.redundant.nonnull.return.annotation=It is not necessary to annotate @Nonnull if you annoted the class with @ReturnValuesAreNonnullByDefault.
-jsr305.return.without.nullness.annotation=Return value must have nullness Annotation (@Nonnull or @CheckForNull)!
+jsr305.return.without.nullness.annotation=Return value must have nullness Annotation (@Nonnull or @CheckForNull).
 jsr305.overridden.methods.allow.only.nonnull=Overriden methods allow only @Nonnull.
-jsr305.need.to.inherit.param.annotations=You have to inherit parameter annotations!
-jsr305.constructor.with.return.annotation=Constructors have no return value and must not be annotated!
+jsr305.need.to.inherit.param.annotations=You have to inherit parameter annotations.
+jsr305.constructor.with.return.annotation=Constructors have no return value and must not be annotated.