added javadoc to function

Author: Sabrina Lawrey

src/main/java/net/openhft/chronicle/testframework/exception/ExceptionTracker.java

@@ -8,21 +8,25 @@
 import java.util.function.Predicate;
 
 /**
- * A test utility class for recording and executing assertions about the presence (or absence) of exceptions
+ * The ExceptionTracker interface provides a set of methods to record, track, and assert exceptions
+ * in a testing context. By defining rules to expect or ignore certain exceptions, it helps in
+ * systematically verifying the correct exception handling behavior of code under test.
  *
  * @param <T> The class used to represent thrown exceptions
  */
 public interface ExceptionTracker<T> {
 
     /**
-     * Create an exception tracker
+     * Factory method to create an instance of the exception tracker. This method encapsulates
+     * the construction of a concrete implementation of the ExceptionTracker interface.
      *
-     * @param messageExtractor   The function used to extract the String message or description from T
-     * @param throwableExtractor The function used to extract the Throwable from T
-     * @param resetRunnable      A Runnable that will be called at the end of {@link #checkExceptions()}
-     * @param exceptions         A map that will be populated with T as the key and the count of occurrences of T as a value
-     * @param ignorePredicate    A predicate that will exclude T's from consideration
-     * @param exceptionRenderer  A function to render T as a String (used when dumping exceptions)
+     * @param messageExtractor   Function to extract the String message or description from T
+     * @param throwableExtractor Function to extract the Throwable from T
+     * @param resetRunnable      Runnable that will be called at the end of {@link #checkExceptions()}
+     * @param exceptions         Map to populate with T as the key and count of occurrences as value
+     * @param ignorePredicate    Predicate to exclude T's from consideration
+     * @param exceptionRenderer  Function to render T as a String (used when dumping exceptions)
+     * @return An instance of ExceptionTracker
      */
     static <T> ExceptionTracker<T> create(@NotNull final Function<T, String> messageExtractor,
                                           @NotNull final Function<T, Throwable> throwableExtractor,
@@ -40,50 +44,54 @@ static <T> ExceptionTracker<T> create(@NotNull final Function<T, String> message
     }
 
     /**
-     * Require than an exception containing the specified string is thrown during the test
+     * Specifies that an exception containing the specified string must be thrown during the test.
+     * Failing to do so will cause the test to fail.
      *
      * @param message The string to require
      */
     void expectException(String message);
 
     /**
-     * Require that an exception matching the specified predicate is thrown
+     * Specifies that an exception matching the specified predicate must be thrown.
+     * Failing to match the exception will cause the test to fail.
      *
-     * @param predicate   The predicate used to match exceptions
-     * @param description The description of the exceptions being required
+     * @param predicate   Predicate to match exceptions
+     * @param description Description of the exceptions being required
      */
     void expectException(Predicate<T> predicate, String description);
 
     /**
-     * Ignore exceptions containing the specified string
+     * Ignores exceptions containing the specified string. Matching exceptions will not cause
+     * the test to fail.
      *
      * @param message The string to ignore
      */
     void ignoreException(String message);
 
     /**
-     * Ignore exceptions matching the specified predicate
+     * Ignores exceptions matching the specified predicate. Matching exceptions will not cause
+     * the test to fail.
      *
-     * @param predicate   The predicate to match the exception
-     * @param description The description of the exceptions being ignored
+     * @param predicate   Predicate to match the exception
+     * @param description Description of the exceptions being ignored
      */
     void ignoreException(Predicate<T> predicate, String description);
 
     /**
-     * Determine if the tracker contains an exception matching the predicate
+     * Determines if the tracker contains an exception matching the predicate.
      *
-     * @param predicate The predicate to match the exception
+     * @param predicate Predicate to match the exception
+     * @return true if an exception matching the predicate is found; false otherwise
      */
     boolean hasException(Predicate<T> predicate);
 
     /**
-     * Call this in @After to ensure
+     * Call this method in a teardown (@After) phase of the test to:
      * <ul>
-     *     <li>No non-ignored exceptions were thrown</li>
-     *     <li>There is an exception matching each of the expected predicates</li>
+     *     <li>Verify no non-ignored exceptions were thrown</li>
+     *     <li>Assert there is an exception matching each of the expected predicates</li>
      * </ul>
-     * <p>
-     * Implementations should throw an exception and print a summary of the assertion(s) violated
+     * Implementations should throw an exception and print a summary if the assertion(s) are violated.
      */
     void checkExceptions();
 }

src/main/java/net/openhft/chronicle/testframework/function/HasName.java

@@ -2,14 +2,23 @@
 
 import org.jetbrains.annotations.NotNull;
 
+/**
+ * This interface represents any object that has a name associated with it.
+ * Implementing this interface allows a class to have a method that retrieves
+ * a name string, providing a consistent way to manage named objects.
+ */
 public interface HasName {
 
     /**
      * Returns the name of this object.
+     * <p>
+     * The name is an identifier that may be used to distinguish this object
+     * from other objects in a collection or system. It is not meant to be unique
+     * necessarily, but should provide meaningful information to the developers or
+     * users.
      *
-     * @return name
+     * @return name - the name associated with this object, must not be null.
      */
     @NotNull
     String name();
-
-}
+}

src/main/java/net/openhft/chronicle/testframework/function/NamedConsumer.java

@@ -7,7 +7,24 @@
 
 import static java.util.Objects.requireNonNull;
 
+/**
+ * The NamedConsumer interface extends both HasName and Consumer interfaces,
+ * thus providing a Consumer with an associated name.
+ * <p>
+ * NamedConsumer can be used in contexts where consumers are managed and identified by their names.
+ *
+ * @param <T> the type of the input to the consumer
+ */
 public interface NamedConsumer<T> extends HasName, Consumer<T> {
+
+    /**
+     * Creates a NamedConsumer instance from the given consumer and name.
+     *
+     * @param consumer the Consumer instance
+     * @param name     the name to associate with the consumer
+     * @return a NamedConsumer wrapping the given consumer and name
+     * @throws NullPointerException if either consumer or name is null
+     */
     @NotNull
     static <T> NamedConsumer<T> of(@NotNull final Consumer<T> consumer,
                                    @NotNull final String name) {
@@ -16,6 +33,15 @@ static <T> NamedConsumer<T> of(@NotNull final Consumer<T> consumer,
         return new VanillaNamedConsumer<>(consumer, name);
     }
 
+    /**
+     * Creates a NamedConsumer instance from the given ThrowingConsumer and name.
+     * ThrowingConsumer is a special type of Consumer that can throw checked exceptions.
+     *
+     * @param consumer the ThrowingConsumer instance
+     * @param name     the name to associate with the consumer
+     * @return a NamedConsumer wrapping the given ThrowingConsumer and name
+     * @throws NullPointerException if either consumer or name is null
+     */
     @NotNull
     static <T> NamedConsumer<T> ofThrowing(@NotNull final ThrowingConsumer<T, ?> consumer,
                                            @NotNull final String name) {

src/main/java/net/openhft/chronicle/testframework/function/ThrowingConsumer.java

@@ -9,13 +9,13 @@
 
 /**
  * Represents an operation that accepts a single input argument and returns no
- * result and that can throw an Exception. Unlike most other functional interfaces, {@code Consumer} is expected
- * to operate via side-effects.
- *
- * <p>This is a <a href="package-summary.html">functional interface</a>
- * whose functional method is {@link #accept(Object)}.
+ * result and that can throw an exception of type {@code X}. Unlike most other functional interfaces,
+ * {@code ThrowingConsumer} is expected to operate via side-effects and may throw exceptions during execution.
+ * <p>
+ * This is a functional interface whose functional method is {@link #accept(Object)}.
  *
  * @param <T> the type of the input to the operation
+ * @param <X> the type of the exception that can be thrown by this operation
  */
 @FunctionalInterface
 public interface ThrowingConsumer<T, X extends Exception> {
@@ -24,16 +24,21 @@ public interface ThrowingConsumer<T, X extends Exception> {
      * Performs this operation on the given argument.
      *
      * @param t the input argument
-     * @throws X if an exception occurs
+     * @throws X if an exception of type {@code X} occurs during execution
      */
     void accept(T t) throws X;
 
     /**
      * Creates and returns a new Consumer that will wrap any exceptions thrown by the
-     * provided {@code throwingConsumer} in a {@link ThrowingConsumerException}
-     * @param throwingConsumer to wrap (non-null)
+     * provided {@code throwingConsumer} in a {@link ThrowingConsumerException}.
+     * <p>
+     * This method allows the integration of a ThrowingConsumer into contexts where a regular
+     * Consumer is expected, by translating checked exceptions into runtime exceptions.
+     *
+     * @param throwingConsumer the ThrowingConsumer to wrap, must not be null
      * @param <T> consumed type
-     * @return a wrapped Consumer
+     * @return a wrapped Consumer that translates checked exceptions into runtime exceptions
+     * @throws NullPointerException if {@code throwingConsumer} is null
      */
     @NotNull
     static <T> Consumer<T> of(@NotNull final ThrowingConsumer<T, ?> throwingConsumer) {

src/main/java/net/openhft/chronicle/testframework/function/ThrowingConsumerException.java

@@ -1,10 +1,28 @@
 package net.openhft.chronicle.testframework.function;
 
+/**
+ * ThrowingConsumerException is a specialized {@link RuntimeException} used to wrap exceptions
+ * thrown by a {@link ThrowingConsumer}.
+ * <p>
+ * This exception allows checked exceptions to be propagated through the ThrowingConsumer interface,
+ * and can be used to handle or log the underlying exceptions as needed.
+ */
 public class ThrowingConsumerException extends RuntimeException {
 
+    /**
+     * The serial version UID for the serialization mechanism.
+     */
     static final long serialVersionUID = -8237762538281151227L;
 
+    /**
+     * Constructs a new ThrowingConsumerException with the specified cause.
+     * <p>
+     * The cause is used to retain necessary information about the underlying exception that
+     * triggered this ThrowingConsumerException, making it available for further inspection or logging.
+     *
+     * @param cause the underlying cause (usually a checked exception thrown by the ThrowingConsumer)
+     */
     public ThrowingConsumerException(Throwable cause) {
         super(cause);
     }
-}
+}

src/main/java/net/openhft/chronicle/testframework/function/TriConsumer.java

@@ -8,6 +8,9 @@
  * result. This is the three-arity specialization of {@link Consumer}.
  * Unlike most other functional interfaces, {@code TriConsumer} is expected
  * to operate via side-effects.
+ * <p>
+ * This can be used anywhere you need to apply an operation to three input parameters
+ * and don't need to return a result, for example, in handling events with three attributes.
  *
  * <p>This is a <a href="package-summary.html">functional interface</a>
  * whose functional method is {@link #accept(Object, Object, Object)}.
@@ -37,6 +40,10 @@ interface TriConsumer<T, U, V> {
      * composed operation.  If performing this operation throws an exception,
      * the {@code after} operation will not be performed.
      *
+     * <p>This can be useful in scenarios where you have several operations that
+     * must be performed on the same set of input parameters, possibly by different parts
+     * of your code.
+     *
      * @param after the operation to perform after this operation
      * @return a composed {@code TriConsumer} that performs in sequence this
      * operation followed by the {@code after} operation