Merge pull request #39 from OpenHFT/gen/javadoc

Gen/javadoc

Author: peter-lawrey

src/main/java/net/openhft/chronicle/testframework/CloseableUtil.java

@@ -3,21 +3,30 @@
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * Utility class to handle closing of {@link java.io.Closeable} or {@link AutoCloseable} resources.
+ * This class provides a method to close a resource without throwing any exceptions, logging them instead.
+ * Since this class is defined as an enum without instances, it cannot be instantiated and is essentially a utility class.
+ */
 public enum CloseableUtil {
-    ;
+    ; // This enum has no instances, acting as a utility class
 
+    // Logger to log warning messages if any exceptions occur while closing the resource
     private static final Logger LOGGER = LoggerFactory.getLogger(CloseableUtil.class);
 
     /**
-     * Close a {@link java.io.Closeable}, logging any exceptions thrown
+     * Closes the provided {@link AutoCloseable} resource quietly, without throwing any exceptions.
+     * If an exception does occur while closing the resource, it is logged as a warning and not propagated.
      *
-     * @param closeable the closeable to close
+     * @param closeable the closeable resource to close, may be any object implementing {@link AutoCloseable}
      */
     public static void closeQuietly(AutoCloseable closeable) {
         try {
-            closeable.close();
+            if (closeable != null) { // Ensuring the closeable is not null to avoid NullPointerException
+                closeable.close();
+            }
         } catch (Exception e) {
-            LOGGER.warn("Error closing", e);
+            LOGGER.warn("Error closing", e); // Logging any exceptions that occur during closing
         }
     }
 }

src/main/java/net/openhft/chronicle/testframework/Combination.java

@@ -21,30 +21,33 @@
 
 import java.util.Collection;
 import java.util.Set;
-import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
 import static java.util.Objects.requireNonNull;
 
 /**
- * General Combination support. The class eagerly calculates all combinations.
+ * Utility class that provides functionality to generate all possible combinations
+ * of a given set of elements. The class eagerly calculates the combinations.
+ * <p>
+ * This class cannot be instantiated.
  *
  * @author Per Minborg
  */
 public final class Combination {
 
     // Suppresses default constructor, ensuring non-instantiability.
-    private Combination() {}
+    private Combination() {
+    }
 
     /**
-     * Creates and returns all possible combinations of the given elements.
+     * Creates and returns a stream of all possible combinations of the given elements.
      * <p>
      * The order of the combinations in the stream is unspecified.
      *
-     * @param <T> element type
-     * @param items to combine
-     * @return all possible combinations of the given elements
-     * @throws NullPointerException if the provided {@code items} list is {@code null}.
+     * @param <T>   element type
+     * @param items the array of items to combine
+     * @return a stream of sets containing all possible combinations of the given elements
+     * @throws NullPointerException if the provided {@code items} array is {@code null}.
      */
     @SafeVarargs
     @SuppressWarnings("varargs") // Creating a Set from an array is safe
@@ -54,36 +57,35 @@ public static <T> Stream<Set<T>> of(@NotNull final T... items) {
     }
 
     /**
-     * Creates and returns all possible combinations of the given elements.
+     * Creates and returns a stream of all possible combinations of the given elements.
      * <p>
      * The order of the combinations in the stream is unspecified.
      *
-     * @param <T> element type
-     * @param items to combine
-     * @return all possible combinations of the given elements
-     * @throws NullPointerException if the provided {@code items} list is {@code null}.
+     * @param <T>   element type
+     * @param items a collection of items to combine
+     * @return a stream of sets containing all possible combinations of the given elements
+     * @throws NullPointerException if the provided {@code items} collection is {@code null}.
      */
     public static <T> Stream<Set<T>> of(@NotNull final Collection<T> items) {
         requireNonNull(items);
         return CombinationUtil.of(items);
     }
 
     /**
-     * Creates and returns all possible combinations of the given elements.
+     * Creates and returns a stream of all possible combinations of the given elements.
      * <p>
      * The order of the combinations in the stream is unspecified.
      * <p>
-     * It is unspecified if the method lazily consume the provided stream before providing
+     * It is unspecified if the method lazily consumes the provided stream before providing
      * the result or not.
      *
-     * @param <T> element type
-     * @param items to combine
-     * @return all possible combinations of the given elements
+     * @param <T>   element type
+     * @param items a stream of items to combine
+     * @return a stream of sets containing all possible combinations of the given elements
      * @throws NullPointerException if the provided {@code items} stream is {@code null}.
      */
     public static <T> Stream<Set<T>> of(@NotNull final Stream<T> items) {
         requireNonNull(items);
         return CombinationUtil.of(items);
     }
-
-}
+}

src/main/java/net/openhft/chronicle/testframework/Delegation.java

@@ -7,30 +7,37 @@
 
 import static java.util.Objects.requireNonNull;
 
+/**
+ * Utility class to build delegator instances that forward method invocations
+ * to a specified delegate object. This class facilitates a fluent API for customizing
+ * the behavior of the delegator.
+ * <p>
+ * This class cannot be instantiated.
+ */
 public final class Delegation {
 
     // Suppresses default constructor, ensuring non-instantiability.
     private Delegation() {
     }
 
     /**
-     * Creates and returns a new builder for a delegator instance that is using the provided
-     * {@code delegate} as a delegate. I.e. methods invoked on a built instance will be delegated to the
+     * Creates and returns a new builder for a delegator instance that will use the provided
+     * {@code delegate} as the delegate. Method invocations on the built instance will be delegated to the
      * provided delegate.
      *
-     * @param delegate to delegate invocations to
-     * @param <D>      provided delegate type
-     * @return new delegator builder
-     * @throws NullPointerException if any provided parameter is {@code null}.
+     * @param delegate The object to delegate invocations to
+     * @param <D>      Provided delegate type
+     * @return New delegator builder
+     * @throws NullPointerException if the provided delegate is {@code null}.
      */
     public static <D> Builder<Object, D> of(@NotNull final D delegate) {
         requireNonNull(delegate);
         return new DelegationBuilder<>(delegate);
     }
 
     /**
-     * The new instance will default it's {@link Object#toString()} method to the one of the
-     * provided delegate.
+     * Interface for building a delegation object. Allows customization of the type view
+     * and the {@code toString()} method of the delegate.
      *
      * @param <T> Target type
      * @param <D> Delegation type
@@ -44,28 +51,29 @@ public interface Builder<T, D> {
          * <p>
          * The default view is {@link Object }.
          *
-         * @param type to view the delegate as (non-null)
-         * @param <N>  the new type of how the delegate should be viewed
-         * @return this builder
+         * @param type The class to view the delegate as (non-null)
+         * @param <N>  The new type of how the delegate should be viewed
+         * @return This builder, for chaining
          */
         <N extends D> Builder<N, D> as(Class<N> type);
 
         /**
-         * Specifies the {@code tostring()) the view should use.
+         * Specifies the {@code toString()} function the view should use.
          * <p>
-         * The default view is {@link Object#toString()}  }.
+         * The default view is {@link Object#toString()}.
          *
-         * @param toStringFunction to be applied to the delegate (non-null)
-         * @return this builder
+         * @param toStringFunction The function to be applied to the delegate (non-null)
+         * @return This builder, for chaining
          */
         Builder<T, D> toStringFunction(Function<? super D, String> toStringFunction);
 
         /**
-         * Creates and returns a new view of type T of the underlying delegate of type D
+         * Creates and returns a new view of type T of the underlying delegate of type D.
+         * <p>
+         * This method finalizes the builder and returns the configured delegator.
          *
-         * @return a new view
+         * @return A new view of the delegate
          */
         T build();
     }
-
-}
+}

src/main/java/net/openhft/chronicle/testframework/ExecutorServiceUtil.java

@@ -3,66 +3,73 @@
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.TimeUnit;
 
+/**
+ * Utility class providing methods to shut down an {@link ExecutorService}
+ * and wait for its termination, with or without forcibly interrupting running tasks.
+ * <p>
+ * This is an enum with no instances, serving solely for namespace control.
+ */
 public enum ExecutorServiceUtil {
     ;
 
     private static final int DEFAULT_TIME_TO_WAIT_SECONDS = 5;
 
     /**
-     * Shut down an executor service, waiting for it to terminate
+     * Shut down an executor service and wait for it to terminate within the given timeout.
      *
      * @param executorService The executor service
-     * @param timeout         The timeout
+     * @param timeout         The maximum time to wait
      * @param unit            The unit of the timeout argument
-     * @throws IllegalStateException if it didn't terminate
+     * @throws IllegalStateException If the executor service didn't terminate within the timeout
      */
     public static void shutdownAndWaitForTermination(ExecutorService executorService, long timeout, TimeUnit unit) {
         executorService.shutdown();
         waitForTermination(executorService, timeout, unit);
     }
 
     /**
-     * Shut down an executor service, wait 5 seconds for it to terminate
+     * Shut down an executor service and wait 5 seconds for it to terminate.
      *
      * @param executorService The executor service
-     * @throws IllegalStateException if it didn't terminate in time
+     * @throws IllegalStateException If it didn't terminate within the default time of 5 seconds
      */
     public static void shutdownAndWaitForTermination(ExecutorService executorService) {
         executorService.shutdown();
         waitForTermination(executorService, DEFAULT_TIME_TO_WAIT_SECONDS, TimeUnit.SECONDS);
     }
 
     /**
-     * Shut down an executor service, interrupting all threads, wait 5 seconds for it to terminate
+     * Shut down an executor service, interrupting all threads, and wait 5 seconds for it to terminate.
      *
      * @param executorService The executor service
-     * @throws IllegalStateException if it didn't terminate in time
+     * @throws IllegalStateException If it didn't terminate within the default time of 5 seconds
      */
     public static void shutdownForciblyAndWaitForTermination(ExecutorService executorService) {
         shutdownForciblyAndWaitForTermination(executorService, DEFAULT_TIME_TO_WAIT_SECONDS, TimeUnit.SECONDS);
     }
 
     /**
-     * Shut down an executor service, interrupting all threads, wait for it to terminate
+     * Shut down an executor service, interrupting all threads, and wait for it to terminate within the given timeout.
      *
      * @param executorService The executor service
-     * @param timeout         The timeout
+     * @param timeout         The maximum time to wait
      * @param unit            The unit of the timeout argument
-     * @throws IllegalStateException if it didn't terminate in time
+     * @throws IllegalStateException If it didn't terminate within the specified timeout
      */
     public static void shutdownForciblyAndWaitForTermination(ExecutorService executorService, long timeout, TimeUnit unit) {
-        executorService.shutdownNow();
+        executorService.shutdownNow(); // Interrupt all running tasks
         waitForTermination(executorService, timeout, unit);
     }
 
+    // Waits for the ExecutorService to terminate within the specified time
     private static void waitForTermination(ExecutorService executorService, long timeToWait, TimeUnit units) {
         try {
             if (!executorService.awaitTermination(timeToWait, units)) {
                 throw new IllegalStateException("ExecutorService didn't shut down");
             }
         } catch (InterruptedException e) {
-            Thread.currentThread().interrupt();
-            throw new IllegalStateException("Interrupted waiting for executor service to shut down");
+            Thread.currentThread().interrupt(); // Restore interrupted status
+            throw new IllegalStateException("Interrupted waiting for executor service to shut down", e);
         }
     }
 }