Issue sevntu-checkstyle#734: required renaming of inner classes, comm…

…ent in pom.xml, examples in Javadoc, contributors' list in README.textile

README.textile

@@ -27,3 +27,5 @@ h3. Contributors
 Hidoyatov Victor, Troshin Sergey, Svinukhov Vladimir, "Ilia Dubinin":https://github.com/sabaka, Dmitry Gridyushko, "Vadym Chekrii":https://github.com/vchekrii, "Vadim Panasiuk":https://github.com/VadimPanasiuk,
 "Aleksey Grigirov":https://github.com/KTannenberg, Alexander Berezovsky, "Sergey Burtsev":https://github.com/burtsevsergey, "Baratali Izmailov":https://github.com/baratali, "Max Vetrenko":https://github.com/maxvetrenko,
 "Pavel Baranchikov":https://github.com/pbaranchikov , "Ashutosh Agarwal":https://github.com/Radsaggi, "Alexey Nesterenko":https://github.com/alexkravin. , ......  for whole list please look at "contributors list":https://github.com/sevntu-checkstyle/sevntu.checkstyle/network/members .
+
+The "Jsr305AnnotationsCheck" is based on the "JSR305CheckstylePlugin":https://github.com/bjrke/JSR305CheckstylePlugin by "Jan Burkhardt":https://github.com/bjrke with contributions from Mattias Nissler, Thorsten Ehlers, Fabian Loewner and Ole Langbehn.

sevntu-checks/pom.xml

@@ -45,7 +45,7 @@
       <scope>test</scope>
       <version>${checkstyle.eclipse-cs.version}</version>
     </dependency>
-    <!-- required for package/jsr305  -->
+    <!-- required for Jsr305AnnotationsCheck -->
     <dependency>
       <groupId>com.google.code.findbugs</groupId>
       <artifactId>jsr305</artifactId>

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

@@ -81,6 +81,55 @@
  * <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>
+ * <p>
+ * Example code:
+ * </p>
+ *
+ * <pre>
+ * // no class-level annotation
+ * class Class1 {
+ *     &#64;CheckForNull // Error: obj2 not annotated!
+ *     String method1(@Nullable Object obj1, Object obj2) { ... }
+ *
+ *     // Error: return value not annotated
+ *     String method2() { ... }
+ * }
+ *
+ * // with class-level defaults
+ * &#64;ParametersAreNonnullByDefault
+ * class Class2 {
+ *     &#64;CheckForNull // Legal
+ *     String method1(Object obj1, Object obj2) { ... }
+ *
+ *     &#64;Nonnull // Legal
+ *     String method2(Object obj1, @Nullable Object obj2) { ... }
+ *
+ *     &#64;Nonnull // Error, redefinition of obj2's nullness
+ *     String method3(Object obj1, @Nonnull Object obj2) { ... }
+ *
+ *     // Error: return value not annotated
+ *     String method4() { ... }
+ * }
+ *
+ * class Class3 implements Interface1 {
+ *    &#64;Override // Legal
+ *    public Object method1(Object obj1, Object obj2) { ... }
+ *
+ *    &#64;Override
+ *    &#64;Nonnull // Legal, return value becomes less "nullable"
+ *    public Object method2(Object obj1, Object obj2) { ... }
+ *
+ *    &#64;Override // Error: Setting a parameter to non-null in an overridden method is illegal
+ *    public Object method3(@Nonnull Object obj1, Object obj2) { ... }
+ *
+ *    &#64;Override // Legal: parameter obj2 becomes more "nullable"
+ *    public Object method4(Object obj1, @Nullable Object obj2) { ... }
+ *
+ *    &#64;Override
+ *    &#64;CheckForNull // Error: return value becomes more "nullable"
+ *    public Object method5() { ... }
+ *}
+ * </pre>
  */
 public class Jsr305AnnotationsCheck extends AbstractCheck {
 
@@ -279,7 +328,7 @@ public final void visitToken(final DetailAST ast) {
             packageExcluded = isPackageExcluded(FullIdent.createFullIdent(nameAST));
         }
         else if (!packageExcluded) {
-            final AbstractJsr305Check handler = handleDefinition(ast);
+            final AbstractJsr305Handler handler = handleDefinition(ast);
             if (handler != null) {
                 handler.check();
             }
@@ -365,28 +414,28 @@ protected boolean isPackageExcluded(final FullIdent fullIdent) {
      *        the ast
      * @return the check.
      */
-    protected AbstractJsr305Check handleDefinition(final DetailAST ast) {
+    protected AbstractJsr305Handler handleDefinition(final DetailAST ast) {
 
         // no definition in catch clause
         final DetailAST parent = ast.getParent();
-        AbstractJsr305Check result = null;
+        AbstractJsr305Handler result = null;
         if (parent == null || parent.getType() != TokenTypes.LITERAL_CATCH) {
             // search modifiers
             final int type = ast.getType();
             switch (type) {
                 case TokenTypes.METHOD_DEF:
-                    result = new MethodJsr305Check(ast);
+                    result = new MethodJsr305Handler(ast);
                     break;
                 case TokenTypes.CTOR_DEF:
-                    result = new ConstructorJsr305Check(ast);
+                    result = new ConstructorJsr305Handler(ast);
                     break;
                 case TokenTypes.PARAMETER_DEF:
-                    result = new ParameterJsr305Check(ast);
+                    result = new ParameterJsr305Handler(ast);
                     break;
                 case TokenTypes.CLASS_DEF:
                 case TokenTypes.INTERFACE_DEF:
                 case TokenTypes.ENUM_DEF:
-                    result = new ClassJsr305Check(ast);
+                    result = new ClassJsr305Handler(ast);
                     break;
                 default:
                     SevntuUtil.reportInvalidToken(ast.getType());
@@ -415,16 +464,16 @@ public void setAllowOverridingParameter(final boolean newAllowOverridingParamete
     }
 
     /**
-     * Class ClassJsr305Check. Checks a class.
+     * Class ClassJsr305Handler. Checks a class.
      */
-    private final class ClassJsr305Check extends AbstractJsr305Check {
+    private final class ClassJsr305Handler extends AbstractJsr305Handler {
 
         /**
          * Constructor.
          * @param ast
          *        the ast
          */
-        protected ClassJsr305Check(final DetailAST ast) {
+        protected ClassJsr305Handler(final DetailAST ast) {
             super(ast);
         }
 
@@ -444,16 +493,16 @@ protected void runcheck() {
     }
 
     /**
-     * Class ParameterJsr305Check. Checks a parameter.
+     * Class ParameterJsr305Handler. Checks a parameter.
      */
-    private final class ParameterJsr305Check extends AbstractJsr305Check {
+    private final class ParameterJsr305Handler extends AbstractJsr305Handler {
 
         /**
          * Constructor.
          * @param ast
          *        the ast
          */
-        protected ParameterJsr305Check(final DetailAST ast) {
+        protected ParameterJsr305Handler(final DetailAST ast) {
             super(ast);
         }
 
@@ -514,16 +563,16 @@ protected void runcheck() {
     }
 
     /**
-     * Class AbstractMethodJsr305Check. A check on a method or constructor (special case).
+     * Class AbstractMethodJsr305Handler. A check on a method or constructor (special case).
      */
-    private abstract class AbstractMethodJsr305Check extends AbstractJsr305Check {
+    private abstract class AbstractMethodJsr305Handler extends AbstractJsr305Handler {
 
         /**
          * Constructor.
          * @param ast
          *        the ast
          */
-        protected AbstractMethodJsr305Check(final DetailAST ast) {
+        protected AbstractMethodJsr305Handler(final DetailAST ast) {
             super(ast);
         }
 
@@ -546,16 +595,16 @@ protected void runcheck() {
     }
 
     /**
-     * Class MethodJsr305Check. A check for a method.
+     * Class MethodJsr305Handler. A check for a method.
      */
-    private final class MethodJsr305Check extends AbstractMethodJsr305Check {
+    private final class MethodJsr305Handler extends AbstractMethodJsr305Handler {
 
         /**
          * Constructor.
          * @param ast
          *        the ast
          */
-        protected MethodJsr305Check(final DetailAST ast) {
+        protected MethodJsr305Handler(final DetailAST ast) {
             super(ast);
         }
 
@@ -620,16 +669,16 @@ protected void runReturnAnnotationCheck() {
     }
 
     /**
-     * Class ConstructorJsr305Check. Check a constructor.
+     * Class ConstructorJsr305Handler. Check a constructor.
      */
-    private final class ConstructorJsr305Check extends AbstractMethodJsr305Check {
+    private final class ConstructorJsr305Handler extends AbstractMethodJsr305Handler {
 
         /**
          * Constructor.
          * @param ast
          *        the ast
          */
-        protected ConstructorJsr305Check(final DetailAST ast) {
+        protected ConstructorJsr305Handler(final DetailAST ast) {
             super(ast);
         }
 
@@ -650,7 +699,7 @@ protected void runReturnAnnotationCheck() {
      * An abstract check, the base for checks on parameters, methods, classes. Class
      * AbstractJsr305Check.
      */
-    public abstract class AbstractJsr305Check {
+    public abstract class AbstractJsr305Handler {
 
         /** Has an error been found. */
         private boolean errorFound;
@@ -664,7 +713,7 @@ public abstract class AbstractJsr305Check {
          * @param ast
          *        the ast
          */
-        protected AbstractJsr305Check(final DetailAST ast) {
+        protected AbstractJsr305Handler(final DetailAST ast) {
             theAst = ast;
             errorFound = false;
             theAnnotations = findAnnotation();