#49 #54 Revise javadoc, add more tests, rename method

Author: ljacqu

src/main/java/ch/jalu/typeresolver/EnumUtil.java

@@ -15,29 +15,29 @@ private EnumUtil() {
     }
 
     /**
-     * Returns the enum entry with the given name if the provided class is an enum and has an entry that matches
-     * exactly the given name. Null is returned otherwise.
+     * Returns an optional of the enum entry with the given name if the provided class is an enum and has an entry that
+     * matches exactly the given name. Otherwise, an empty optional is returned.
      *
      * @param clazz the class to check for enum entries, or null
      * @param name the name to match, or null
      * @param <T> the class type
-     * @return the enum entry if the name was non-null, the class was an enum and had such an enum entry; null otherwise
+     * @return optional of the enum entry if the class is an enum and has an entry of the given name; empty otherwise
      */
-    @Nullable
     @SuppressWarnings({"unchecked", "rawtypes"})
-    public static <T> T valueOfOrNull(@Nullable Class<T> clazz, @Nullable String name) {
+    public static <T> Optional<T> tryValueOf(@Nullable Class<T> clazz, @Nullable String name) {
         if (clazz == null || !clazz.isEnum() || name == null) {
-            return null;
+            return Optional.empty();
         }
         try {
-            return (T) Enum.valueOf((Class) clazz, name);
+            return Optional.of((T) Enum.valueOf((Class) clazz, name));
         } catch (IllegalArgumentException ignored) {
-            return null;
+            return Optional.empty();
         }
     }
 
     /**
-     * Specifies whether the given class is an enum or a synthetic class of an enum entry.
+     * Indicates whether the given class is an enum or a synthetic class of an enum entry. Synthetic classes are
+     * created when an enum entry extends the enum type anonymously.
      * <p>
      * Examples:<pre>{@code
      *   Class<?> class1 = NumericShaper.Range.class;

src/main/java/ch/jalu/typeresolver/classutil/ClassType.java

@@ -9,8 +9,8 @@ public enum ClassType {
     ENUM,
 
     /**
-     * The class is the synthetic class of an enum entry that anonymously extends the base type. This class returns
-     * false for {@link Class#isEnum()} but is assignable to {@link Enum}.
+     * The class is the synthetic class of an enum entry that anonymously extends the enum type. Although this class
+     * returns {@code false} for the {@link Class#isEnum()} method, it is assignable to the {@link Enum} type.
      * <br>Example: {@code NumericShaper.Range.ETHIOPIC.getClass()}
      */
     ENUM_ENTRY,
@@ -35,7 +35,7 @@ public enum ClassType {
     PRIMITIVE,
 
     /**
-     * The class is an array, such as {@code String[]}.
+     * The class is an array, such as {@code String[].class} or {@code int[].class}.
      *
      * @see ch.jalu.typeresolver.array.ArrayClassProperties
      */
@@ -54,8 +54,11 @@ public enum ClassType {
 
     /**
      * The class is a "regular" Java class, which typically means it was declared with the {@code class} or
-     * {@code record} keyword. An enum type is also considered a "regular class".
+     * {@code record} keyword. A class is considered a "regular class" by exclusion: it is a "regular class" if none of
+     * the other types of this enum apply to it.
      * <br>Example: {@link String}
+     * <p>
+     * Note that nested classes and anonymous classes may also be considered "regular classes".
      */
     REGULAR_CLASS
 

src/main/java/ch/jalu/typeresolver/classutil/ClassTypeCallback.java

@@ -5,7 +5,8 @@
 
 /**
  * Extendable class with a method dedicated for each {@link ClassType}, with appropriately cast method parameters.
- * This class's methods are meant to be (partially) overridden.
+ * This class's methods are meant to be overridden. The methods can be overridden partially if only certain class types
+ * are of interest.
  *
  * @param <R> the result type of the callback
  * @see ClassUtil#processClassByType
@@ -63,7 +64,8 @@ public R forPrimitiveType(Class<?> primitiveClass) {
     /**
      * Called when the class to process is an array class, such as {@code int[].class} or {@code String[][].class}.
      * <p>
-     * Note that the class cannot be blindly cast to {@code Class<? extends Object[]>} due to arrays of primitive types.
+     * Note that the class cannot be cast to {@code Class<? extends Object[]>} without checking beforehand, due to
+     * arrays of primitive types such as {@code int[].class}.
      *
      * @param arrayClass the array class
      * @return result or null
@@ -96,7 +98,7 @@ public R forProxyClass(Class<?> proxyClass) {
     }
 
     /**
-     * Called when the class to process is a "regular class" (cf. {@link ClassUtil#isActualJavaClass}).
+     * Called when the class to process is a "regular class", as explained in {@link ClassUtil#isRegularJavaClass}.
      *
      * @param regularClass the Java class
      * @return result or null

src/main/java/ch/jalu/typeresolver/classutil/ClassUtil.java

@@ -47,6 +47,9 @@ public static Optional<Class<?>> tryLoadClass(String name) {
     /**
      * Loads a class or throws an {@link IllegalArgumentException}. This method wraps {@link Class#forName(String)}
      * to throw a runtime exception for convenience.
+     * <p>
+     * Note that errors thrown by {@link Class#forName(String)} (e.g. {@link LinkageError}) are not caught as they
+     * typically indicate more severe issues.
      *
      * @param name the class name to load
      * @return the loaded class, never null
@@ -61,8 +64,7 @@ public static Class<?> loadClassOrThrow(String name) {
 
     /**
      * Returns the {@link Class#getName() class name} of the object null-safely, returning "null" if the object is null.
-     * See also {@link #getSemanticName(Object)} for another null-safe, more user-appropriate name of an object
-     * or class.
+     * Use {@link #getSemanticName(Object)} to generate a null-safe, more user-appropriate name of the object's type.
      *
      * @param object the object whose type should be returned as string
      * @return the object's class name, or "null" if the object was null
@@ -147,8 +149,8 @@ public static String getSemanticName(@Nullable Class<?> clazz) {
      * @param clazz the class to inspect, or null
      * @return true if the class is a "regular Java class"
      */
-    public static boolean isActualJavaClass(@Nullable Class<?> clazz) {
-        return clazz != null && getType(clazz) == ClassType.REGULAR_CLASS;
+    public static boolean isRegularJavaClass(@Nullable Class<?> clazz) {
+        return getType(clazz) == ClassType.REGULAR_CLASS;
     }
 
     /**
@@ -179,8 +181,8 @@ public static ClassType getType(Class<?> clazz) {
     }
 
     /**
-     * Returns the result obtained by the given's {@link ClassTypeCallback} method that is applicable for the given
-     * class's type.
+     * Calls the method on the given {@link ClassTypeCallback} that corresponds to the given class's type and
+     * returns the result.
      *
      * @param clazz the class to inspect and process
      * @param typeCallback the type callback to generate a result with

src/test/java/ch/jalu/typeresolver/EnumUtilTest.java

@@ -15,7 +15,6 @@
 import static org.hamcrest.Matchers.contains;
 import static org.hamcrest.Matchers.empty;
 import static org.hamcrest.Matchers.equalTo;
-import static org.hamcrest.Matchers.nullValue;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
@@ -65,16 +64,20 @@ void shouldHaveValidJavadocExampleOnAsEnumType() {
     @Test
     void shouldTryToResolveNameToEntry() {
         // given / when / then
-        assertThat(EnumUtil.valueOfOrNull(TestEnum.class, "FIRST"), equalTo(TestEnum.FIRST));
-        assertThat(EnumUtil.valueOfOrNull(TestEnum.class, "SECOND"), equalTo(TestEnum.SECOND));
-        assertThat(EnumUtil.valueOfOrNull(TestEnum.class, "THIRD"), equalTo(TestEnum.THIRD));
-        assertThat(EnumUtil.valueOfOrNull(TimeUnit.class, "MINUTES"), equalTo(TimeUnit.MINUTES));
-
-        assertThat(EnumUtil.valueOfOrNull(TestEnum.class, null), nullValue());
-        assertThat(EnumUtil.valueOfOrNull(TestEnum.class, "WRONG"), nullValue());
-        assertThat(EnumUtil.valueOfOrNull(null, "ENTRY"), nullValue());
-        assertThat(EnumUtil.valueOfOrNull(HashMap.class, "WRONG"), nullValue());
-        assertThat(EnumUtil.valueOfOrNull(TimeUnit.class, "WRONG"), nullValue());
+        assertThat(EnumUtil.tryValueOf(TestEnum.class, "FIRST"), equalTo(Optional.of(TestEnum.FIRST)));
+        assertThat(EnumUtil.tryValueOf(TestEnum.class, "SECOND"), equalTo(Optional.of(TestEnum.SECOND)));
+        assertThat(EnumUtil.tryValueOf(TestEnum.class, "THIRD"), equalTo(Optional.of(TestEnum.THIRD)));
+        assertThat(EnumUtil.tryValueOf(TimeUnit.class, "MINUTES"), equalTo(Optional.of(TimeUnit.MINUTES)));
+        assertThat(EnumUtil.tryValueOf(TestEnum.NestedEnum.class, "SECOND"), equalTo(Optional.of(TestEnum.NestedEnum.SECOND)));
+
+        assertThat(EnumUtil.tryValueOf(null, null), equalTo(Optional.empty()));
+        assertThat(EnumUtil.tryValueOf(TestEnum.class, null), equalTo(Optional.empty()));
+        assertThat(EnumUtil.tryValueOf(null, "ENTRY"), equalTo(Optional.empty()));
+
+        assertThat(EnumUtil.tryValueOf(TestEnum.class, "WRONG"), equalTo(Optional.empty()));
+        assertThat(EnumUtil.tryValueOf(TestEnum.NestedEnum.class, "WRONG"), equalTo(Optional.empty()));
+        assertThat(EnumUtil.tryValueOf(HashMap.class, "WRONG"), equalTo(Optional.empty()));
+        assertThat(EnumUtil.tryValueOf(TimeUnit.class, "WRONG"), equalTo(Optional.empty()));
     }
 
     @Test
@@ -146,7 +149,7 @@ private enum TestEnum {
         FIRST,
 
         SECOND() {
-            class InsideSecondClass {
+            class InsideSecondClass { // Referenced via TestEnum.SECOND.getClass().getDeclaredClasses()[0];
 
             }
         },