Fix java doc issues (#98)

* Fix java doc issues

* spotless

annotation/src/main/java/module-info.java

@@ -1,3 +1,4 @@
+/** A dependency free module containing common annotation types */
 module creek.base.annotation {
     exports org.creekservice.api.base.annotation;
     exports org.creekservice.api.base.annotation.schema;

schema/src/main/java/module-info.java

@@ -1,3 +1,4 @@
+/** Module containing base code for working with Schemas. */
 module creek.base.schema {
     requires creek.base.annotation;
     requires io.github.classgraph;

schema/src/main/java/org/creekservice/api/base/schema/GeneratesSchemas.java

@@ -27,18 +27,24 @@
 import java.util.stream.Collectors;
 import org.creekservice.api.base.annotation.schema.GeneratesSchema;
 
-/**
- * Used to find instances of classes on the class or module path that are annotated with {@link
- * GeneratesSchema}.
- */
+/** Utility class for working with {@link GeneratesSchema} annotated types. */
 public final class GeneratesSchemas {
 
     private GeneratesSchemas() {}
 
+    /**
+     * Factory method for {@link Scanner}
+     *
+     * @return new scanner instance
+     */
     public static Scanner scanner() {
         return new Scanner();
     }
 
+    /**
+     * Used to find instances of classes on the class or module path that are annotated with {@link
+     * GeneratesSchema}.
+     */
     public static final class Scanner {
 
         private final Set<String> allowedPackages = new HashSet<>();

schema/src/main/java/org/creekservice/api/base/schema/naming/SubTypeNaming.java

@@ -35,6 +35,7 @@ private SubTypeNaming() {}
      *
      * @param subType the subtype of the {@code baseType}
      * @param baseType the base type
+     * @param <T> the base type
      * @return the subtype name
      */
     public static <T> String subTypeName(
@@ -56,6 +57,7 @@ public static <T> String subTypeName(
      *
      * @param subType the subtype of the {@code baseType}
      * @param baseTypeName the base type's simple name
+     * @param <T> the base type
      * @return the subtype name
      */
     public static <T> String subTypeName(

type/src/main/java/module-info.java

@@ -1,3 +1,4 @@
+/** Module containing types used by many other Creek modules */
 module creek.base.type {
     requires transitive creek.base.annotation;
 

type/src/main/java/org/creekservice/api/base/type/Iterators.java

@@ -30,7 +30,9 @@ private Iterators() {}
     /**
      * An iterator that iterates over the elements in a list in reverse.
      *
+     * @param list the list to reverse
      * @param <E> the element type.
+     * @return reverse iterator
      */
     public static <E> Iterator<E> reverseIterator(final List<E> list) {
         return new ReverseListIterator<>(list);

type/src/main/java/org/creekservice/api/base/type/Lists.java

@@ -20,10 +20,19 @@
 import java.util.ArrayList;
 import java.util.List;
 
+/** Util class for working with {@code List}. */
 public final class Lists {
 
     private Lists() {}
 
+    /**
+     * Combine to lists
+     *
+     * @param a first list
+     * @param b second list
+     * @param <T> element type
+     * @return a list containing all the elements from {@code a} and then from {@code b}
+     */
     public static <T> List<T> combineList(final List<? extends T> a, final List<? extends T> b) {
         final List<T> result = new ArrayList<>(a);
         result.addAll(b);

type/src/main/java/org/creekservice/api/base/type/Preconditions.java

@@ -22,6 +22,7 @@
 import java.util.Map;
 import java.util.Objects;
 
+/** Factory methods for asserting preconditions */
 public final class Preconditions {
 
     private Preconditions() {}
@@ -31,6 +32,7 @@ private Preconditions() {}
      *
      * @param value the collection to test.
      * @param name the name to use in the exception, if the check fails.
+     * @param <T> the value type
      * @return {@code value} if the check passes.
      */
     public static <T> T[] requireNonEmpty(final T[] value, final String name) {
@@ -46,6 +48,7 @@ public static <T> T[] requireNonEmpty(final T[] value, final String name) {
      *
      * @param value the collection to test.
      * @param name the name to use in the exception, if the check fails.
+     * @param <T> the value type
      * @return {@code value} if the check passes.
      */
     public static <T extends Collection<?>> T requireNonEmpty(final T value, final String name) {
@@ -61,6 +64,7 @@ public static <T extends Collection<?>> T requireNonEmpty(final T value, final S
      *
      * @param value the map to test.
      * @param name the name to use in the exception, if the check fails.
+     * @param <T> the value type
      * @return {@code value} if the check passes.
      */
     public static <T extends Map<?, ?>> T requireNonEmpty(final T value, final String name) {
@@ -107,6 +111,7 @@ public static String requireNonBlank(final String value, final String name) {
      * @param a the first value to test
      * @param b the second value to test
      * @param msg the message to use in the exception if the check fails.
+     * @param <T> the value type
      */
     public static <T> void requireEqual(final T a, final T b, final String msg) {
         if (!Objects.equals(a, b)) {
@@ -120,7 +125,7 @@ public static <T> void requireEqual(final T a, final T b, final String msg) {
      * @param value the value to test
      * @param upperBound the upper bound of valid values for {@code value}
      * @param msg the message prefix
-     * @param <T> the type
+     * @param <T> the value type
      */
     public static <T extends Comparable<T>> void requireLessThan(
             final T value, final T upperBound, final String msg) {
@@ -136,7 +141,7 @@ public static <T extends Comparable<T>> void requireLessThan(
      * @param value the value to test
      * @param upperBound the upper bound of valid values for {@code value}
      * @param msg the message prefix
-     * @param <T> the type
+     * @param <T> the value type
      */
     public static <T extends Comparable<T>> void requireLessThanOrEqualTo(
             final T value, final T upperBound, final String msg) {
@@ -152,7 +157,7 @@ public static <T extends Comparable<T>> void requireLessThanOrEqualTo(
      * @param value the value to test
      * @param lowerBound the lower bound of valid values for {@code value}
      * @param msg the message prefix
-     * @param <T> the type
+     * @param <T> the value type
      */
     public static <T extends Comparable<T>> void requireGreaterThan(
             final T value, final T lowerBound, final String msg) {
@@ -168,7 +173,7 @@ public static <T extends Comparable<T>> void requireGreaterThan(
      * @param value the value to test
      * @param lowerBound the lower bound of valid values for {@code value}
      * @param msg the message prefix
-     * @param <T> the type
+     * @param <T> the value type
      */
     public static <T extends Comparable<T>> void requireGreaterThanOrEqualTo(
             final T value, final T lowerBound, final String msg) {

type/src/main/java/org/creekservice/api/base/type/Primitives.java

@@ -41,22 +41,40 @@ public final class Primitives {
 
     private Primitives() {}
 
-    /** @return {@code true} if {@code type} is a primitive type */
+    /**
+     * Test if type is unboxed primitive.
+     *
+     * @param type the type to check
+     * @return {@code true} if {@code type} is a primitive type
+     */
     public static boolean isUnboxedPrimitive(final Class<?> type) {
         return PRIMITIVES.containsKey(type);
     }
 
-    /** @return {@code true} if {@code type} is a wrapper type for a primitive */
+    /**
+     * Test if type is boxed primitive.
+     *
+     * @param type the type to check
+     * @return {@code true} if {@code type} is a wrapper type for a primitive
+     */
     public static boolean isBoxedPrimitive(final Class<?> type) {
         return BOXED.containsKey(type);
     }
 
-    /** @return if {@code type} is a primitive: it's boxed type, otherwise {@code type}. */
+    /**
+     * Convert type to its boxed equivalent, where one exists
+     *
+     * @param type the type to box
+     * @return if {@code type} is a primitive: it's boxed type, otherwise {@code type}.
+     */
     public static Class<?> box(final Class<?> type) {
         return PRIMITIVES.getOrDefault(type, type);
     }
 
     /**
+     * Convert type to its unboxed equivalent, where one exists
+     *
+     * @param type the type to unbox
      * @return if {@code type} is a boxed primitive: it's primitive type, otherwise {@code type}.
      */
     public static Class<?> unbox(final Class<?> type) {

type/src/main/java/org/creekservice/api/base/type/RuntimeIOException.java

@@ -22,10 +22,23 @@
 /** As checked exceptions are a PITA. */
 public final class RuntimeIOException extends RuntimeException {
 
+    /**
+     * Factory method
+     *
+     * @param cause exception to wrap
+     * @return new instance
+     */
     public static RuntimeIOException runtimeIOException(final IOException cause) {
         return new RuntimeIOException(cause);
     }
 
+    /**
+     * Factory method
+     *
+     * @param msg the exception msg
+     * @param cause exception to wrap
+     * @return new instance
+     */
     public static RuntimeIOException runtimeIOException(final String msg, final IOException cause) {
         return new RuntimeIOException(msg, cause);
     }

type/src/main/java/org/creekservice/api/base/type/Suppliers.java

@@ -20,17 +20,25 @@
 
 import java.util.function.Supplier;
 
+/** Factory methods for creating {@link Supplier suppliers} */
 public final class Suppliers {
 
     private Suppliers() {}
 
+    /**
+     * Create a Supplier that will cache the value returned from the {@code delegate} on first use.
+     *
+     * @param delegate the delegate that will be called once on first use.
+     * @param <T> the type of the supplier
+     * @return a caching Supplier.
+     */
     public static <T> Supplier<T> memoize(final Supplier<T> delegate) {
         return (delegate instanceof MemorizingSupplier)
                 ? delegate
                 : new MemorizingSupplier<>(delegate);
     }
 
-    public static final class MemorizingSupplier<T> implements Supplier<T> {
+    private static final class MemorizingSupplier<T> implements Supplier<T> {
 
         private final Supplier<T> delegate;
         private final Object lock = new Object();

type/src/main/java/org/creekservice/api/base/type/Throwables.java

@@ -20,10 +20,17 @@
 import java.io.PrintWriter;
 import java.io.StringWriter;
 
+/** Utility class for working with {@link Throwable} */
 public final class Throwables {
 
     private Throwables() {}
 
+    /**
+     * Get the stack trace of the supplied {@link Throwable}.
+     *
+     * @param t the throwable
+     * @return the stack trace
+     */
     public static String stackTrace(final Throwable t) {
         final StringWriter sw = new StringWriter();
         t.printStackTrace(new PrintWriter(sw));

type/src/main/java/org/creekservice/api/base/type/config/SystemEnv.java

@@ -151,6 +151,7 @@ public static Duration readDuration(final String name, final Duration defaultVal
      *
      * @param name the name of the variable to read
      * @param defaultValue supplier of a default insstance to use if the variable is not set.
+     * @param <T> The type to instantiate
      * @return the instance of the type set in the variable, or the result of {@code
      *     defaultValue.get()} if not set.
      */
@@ -168,6 +169,11 @@ public static <T> T readInstance(final String name, final Supplier<? extends T>
         }
     }
 
+    /**
+     * Hidden.
+     *
+     * @hidden
+     */
     private static final class EnvException extends IllegalArgumentException {
 
         EnvException(

type/src/main/java/org/creekservice/api/base/type/config/SystemProperties.java

@@ -26,26 +26,65 @@ public final class SystemProperties {
 
     private SystemProperties() {}
 
+    /**
+     * Get a string system property
+     *
+     * @param name the property name
+     * @return the property
+     */
     public static Optional<String> getString(final String name) {
         return Optional.ofNullable(property(name, null, String.class, Function.identity()));
     }
 
+    /**
+     * Get a string system property
+     *
+     * @param name the property name
+     * @param defaultVal the default value to use if property not set
+     * @return the property, or the supplied default.
+     */
     public static String getString(final String name, final String defaultVal) {
         return property(name, defaultVal, String.class, Function.identity());
     }
 
+    /**
+     * Get an int system property
+     *
+     * @param name the property name
+     * @return the property
+     */
     public static Optional<Integer> getInt(final String name) {
         return Optional.ofNullable(property(name, null, int.class, Integer::parseInt));
     }
 
+    /**
+     * Get an int system property
+     *
+     * @param name the property name
+     * @param defaultVal the default value to use if property not set
+     * @return the property, or the supplied default.
+     */
     public static int getInt(final String name, final int defaultVal) {
         return property(name, defaultVal, int.class, Integer::parseInt);
     }
 
+    /**
+     * Get a long system property
+     *
+     * @param name the property name
+     * @return the property
+     */
     public static Optional<Long> getLong(final String name) {
         return Optional.ofNullable(property(name, null, long.class, Long::parseLong));
     }
 
+    /**
+     * Get a long system property
+     *
+     * @param name the property name
+     * @param defaultVal the default value to use if property not set
+     * @return the property, or the supplied default.
+     */
     public static Long getLong(final String name, final long defaultVal) {
         return property(name, defaultVal, long.class, Long::parseLong);
     }
@@ -67,6 +106,7 @@ private static <T> T property(
         }
     }
 
+    /** @hidden */
     @VisibleForTesting
     static final class ParseException extends RuntimeException {
         ParseException(

type/src/main/java/org/creekservice/api/base/type/temporal/AccurateClock.java

@@ -22,6 +22,11 @@
 /** Default clock impl. */
 public final class AccurateClock implements Clock {
 
+    /**
+     * Create instance
+     *
+     * @return new instance
+     */
     public static Clock create() {
         return new AccurateClock();
     }

type/src/main/java/org/creekservice/api/base/type/temporal/Clock.java

@@ -23,5 +23,10 @@
 @FunctionalInterface
 public interface Clock {
 
+    /**
+     * Get current time.
+     *
+     * @return current time.
+     */
     Instant get();
 }