Add missing license preambule, Enhancing UtilsVerifier docs, Fixing javadoc generator warnings (#6)

Author: ajoz

src/main/java/com/github/karczews/utilsverifier/Arrays2.java

@@ -1,3 +1,15 @@
+/**
+ * Copyright (c) 2017-present, UtilsVerifier Contributors.
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
+ * compliance with the License. You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is
+ * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
+ * the License for the specific language governing permissions and limitations under the License.
+ */
 package com.github.karczews.utilsverifier;
 
 /**

src/main/java/com/github/karczews/utilsverifier/UtilsVerifier.java

@@ -19,8 +19,8 @@
 import java.lang.reflect.Modifier;
 
 /**
- * {@code EqualsVerifier} tool can be used in unit tests to verify if certain util class is
- * well formed.
+ * {@code UtilsVerifier} tool can be used in unit tests to verify if certain
+ * util class is well formed.
  * <p>
  * By default verifier performs following checks that class:
  * <ul>
@@ -29,8 +29,24 @@
  * <li> has no instance fields
  * <li> has no mutable static fields
  * </ul>
+ * <p>
+ * If any of the following checks fails then an {@link AssertionError} will be
+ * thrown with an appropriate information about the cause.
+ * <p>
+ * Basic usage:
+ * <pre>
+ * {@code UtilsVerifier.forClass(TestedClass.class).verify();}
+ * </pre>
+ * It's not advised, but possible to suppress one or more of the checks with
+ * builder methods.
+ * <p>
+ * Example suppress:
+ * <pre>
+ * {@code UtilsVerifier.forClass(TestClass.class).suppressFinalClassCheck(true).verify();}
+ * </pre>
  *
  * @param <T> class under test
+ * @see AssertionError
  */
 public final class UtilsVerifier<T> {
 
@@ -53,17 +69,22 @@ private UtilsVerifier(final Class<T> type) {
     }
 
     /**
-     * Creates UtilsVerifier instance for provided type.
+     * Creates UtilsVerifier instance for the provided type.
      *
-     * @param type class type for which verifier will be created
+     * @param type class type for a which verifier will be created
+     * @param <T>  type of the class to verify
+     * @return UtilsVerifier instance
      */
     public static <T> UtilsVerifier<T> forClass(final Class<T> type) {
         return new UtilsVerifier<T>(type);
     }
 
     /**
-     * Performs verification for provided type.
-     * {@link AssertionError} will be thrown if provided type is not well formed util class.
+     * Performs verification for the type that the {@link UtilsVerifier} was
+     * created with.
+     * <p>
+     * {@link AssertionError} will be thrown if provided type is not a well
+     * formed util class.
      */
     public void verify() {
         checkIfClassIsFinal();
@@ -78,6 +99,7 @@ public void verify() {
      * Sets exception type that will be expected during construction attempt.
      *
      * @param type expected exception type
+     * @return UtilsVerifier instance
      */
     public UtilsVerifier<T> withConstructorThrowing(final Class<? extends Throwable> type) {
         expectedConstructorException = type;
@@ -88,61 +110,67 @@ public UtilsVerifier<T> withConstructorThrowing(final Class<? extends Throwable>
      * Suppress final class verification. Use if non-final util class is allowed.
      *
      * @param suppressCheck true if check should be suppressed, false otherwise
+     * @return UtilsVerifier instance
      */
     public UtilsVerifier<T> suppressFinalClassCheck(final boolean suppressCheck) {
         suppressFinalClassCheck = suppressCheck;
         return this;
     }
 
     /**
-     * Suppress single constructor verification.
-     * Use if util class is allowed to have more than one constructor.
+     * Suppress single constructor verification. Use if util class is allowed to
+     * have more than one constructor.
      *
      * @param suppressCheck true if check should be suppressed, false otherwise
+     * @return UtilsVerifier instance
      */
     public UtilsVerifier<T> suppressOnlyOneConstructorCheck(final boolean suppressCheck) {
         suppressOnlyOneConstructorCheck = suppressCheck;
         return this;
     }
 
     /**
-     * Suppress private constructor verification.
-     * Use if util class is allowed to have non private constructor.
+     * Suppress private constructor verification. Use if util class is allowed
+     * to have non private constructor.
      *
      * @param suppressCheck true if check should be suppressed, false otherwise
+     * @return UtilsVerifier instance
      */
     public UtilsVerifier<T> suppressPrivateConstructorCheck(final boolean suppressCheck) {
         suppressPrivateConstructorCheck = suppressCheck;
         return this;
     }
 
     /**
-     * Suppress instance field verification.
-     * Use if util class is allowed to have instance fields.
+     * Suppress instance field verification. Use if util class is allowed to
+     * have instance fields.
      *
      * @param suppressCheck true if check should be suppressed, false otherwise
+     * @return UtilsVerifier instance
      */
     public UtilsVerifier<T> suppressInstanceFieldCheck(final boolean suppressCheck) {
         suppressInstanceFieldCheck = suppressCheck;
         return this;
     }
 
     /**
-     * Suppress instance method verification.
-     * Use if util class is allowed to have instance methods.
+     * Suppress instance method verification. Use if util class is allowed to
+     * have instance methods.
      *
      * @param suppressCheck true if check should be suppressed, false otherwise
+     * @return UtilsVerifier instance
      */
     public UtilsVerifier<T> suppressInstanceMethodCheck(final boolean suppressCheck) {
         suppressInstanceMethodCheck = suppressCheck;
         return this;
     }
 
     /**
-     * Suppress static mutable fields verification.
-     * Use if util class is allowed to have mutable static fields.
+     * Suppress static mutable fields verification. Use if util class is allowed
+     * to have mutable static fields.
      *
      * @param suppressCheck true if check should be suppressed, false otherwise
+     * @return UtilsVerifier instance
      */
     public UtilsVerifier<T> suppressMutableStaticFieldsCheck(final boolean suppressCheck) {
         suppressMutableStaticFieldsCheck = suppressCheck;
@@ -218,12 +246,11 @@ private void hasNoMutableStaticFields() {
         if (suppressMutableStaticFieldsCheck) return;
         final Field[] fields = classUnderTest.getDeclaredFields();
 
-        fields:
         for (int index = 0; index < fields.length; index++) {
             final Field field = fields[index];
             final int modifiers = field.getModifiers();
             if (Arrays2.contains(field.getName(), allowedMutableStaticFields)) {
-                continue fields;
+                continue;
             }
             if (Modifier.isStatic(modifiers) && !Modifier.isFinal(modifiers)) {
                 throw new AssertionError(classUnderTest.getName()

src/test/java/com/github/karczews/utilsverifier/subjects/ImmutableStaticFields.java

@@ -1,3 +1,15 @@
+/**
+ * Copyright (c) 2017-present, UtilsVerifier Contributors.
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
+ * compliance with the License. You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is
+ * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
+ * the License for the specific language governing permissions and limitations under the License.
+ */
 package com.github.karczews.utilsverifier.subjects;
 
 public final class ImmutableStaticFields {

src/test/java/com/github/karczews/utilsverifier/subjects/MutableStaticFields.java

@@ -1,3 +1,15 @@
+/**
+ * Copyright (c) 2017-present, UtilsVerifier Contributors.
+ * <p>
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
+ * compliance with the License. You may obtain a copy of the License at
+ * <p>
+ * http://www.apache.org/licenses/LICENSE-2.0
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is
+ * distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
+ * the License for the specific language governing permissions and limitations under the License.
+ */
 package com.github.karczews.utilsverifier.subjects;
 
 public final class MutableStaticFields {