Cleanup work

6 files changed, 161 insertions, 68 deletions

diff --git a/base/src/main/java/bjc/utils/data/internals/BoundLazy.java b/base/src/main/java/bjc/utils/data/internals/BoundLazy.java
index f71d32b..b160c0c 100644
--- a/base/src/main/java/bjc/utils/data/internals/BoundLazy.java
+++ b/base/src/main/java/bjc/utils/data/internals/BoundLazy.java
@@ -9,37 +9,35 @@ import bjc.utils.data.Lazy;
 import bjc.utils.funcdata.FunctionalList;
 import bjc.utils.funcdata.IList;
 
-/*
- * Implements a lazy holder that has been bound
+/**
+ * Implements a lazy holder that has been bound.
+ *
+ * @author Ben Culkin
  */
 public class BoundLazy<OldType, BoundContainedType> implements IHolder<BoundContainedType> {
-	/*
-	 * The old value
-	 */
+	/* The old value. */
 	private final Supplier<IHolder<OldType>> oldSupplier;
 
-	/*
-	 * The function to use to transform the old value into a new value
-	 */
+	/* The function to use to transform the old value into a new value. */
 	private final Function<OldType, IHolder<BoundContainedType>> binder;
 
-	/*
-	 * The bound value being held
-	 */
+	/* The bound value being held. */
 	private IHolder<BoundContainedType> boundHolder;
 
-	/*
-	 * Whether the bound value has been actualized or not
-	 */
+	/* Whether the bound value has been actualized or not. */
 	private boolean holderBound;
 
-	/*
-	 * Transformations currently pending on the bound value
-	 */
+	/* Transformations currently pending on the bound value. */
 	private final IList<UnaryOperator<BoundContainedType>> actions = new FunctionalList<>();
 
-	/*
-	 * Create a new bound lazy value
+	/**
+	 * Create a new bound lazy value. 
+	 *
+	 * @param supp
+	 * 	The supplier of the old value.
+	 *
+	 * @param binder
+	 * 	The function to use to bind the old value to the new one.
 	 */
 	public BoundLazy(final Supplier<IHolder<OldType>> supp,
 			final Function<OldType, IHolder<BoundContainedType>> binder) {
@@ -51,28 +49,20 @@ public class BoundLazy<OldType, BoundContainedType> implements IHolder<BoundCont
 	public <BoundType> IHolder<BoundType> bind(final Function<BoundContainedType, IHolder<BoundType>> bindr) {
 		if (bindr == null) throw new NullPointerException("Binder must not be null");
 
-		/*
-		 * Prepare a list of pending actions
-		 */
+		/* Prepare a list of pending actions. */
 		final IList<UnaryOperator<BoundContainedType>> pendingActions = new FunctionalList<>();
 		actions.forEach(pendingActions::add);
 
-		/*
-		 * Create the new supplier of a value
-		 */
+		/* Create the new supplier of a value. */
 		final Supplier<IHolder<BoundContainedType>> typeSupplier = () -> {
 			IHolder<BoundContainedType> oldHolder = boundHolder;
 
-			/*
-			 * Bind the value if it hasn't been bound before
-			 */
+			/* Bind the value if it hasn't been bound before. */
 			if (!holderBound) {
 				oldHolder = oldSupplier.get().unwrap(binder);
 			}
 
-			/*
-			 * Apply all the pending actions
-			 */
+			/* Apply all the pending actions. */
 			return pendingActions.reduceAux(oldHolder, (action, state) -> {
 				return state.transform(action);
 			}, (value) -> value);
@@ -95,19 +85,20 @@ public class BoundLazy<OldType, BoundContainedType> implements IHolder<BoundCont
 	public <MappedType> IHolder<MappedType> map(final Function<BoundContainedType, MappedType> mapper) {
 		if (mapper == null) throw new NullPointerException("Mapper must not be null");
 
-		// Prepare a list of pending actions
+		/* Prepare a list of pending actions. */
 		final IList<UnaryOperator<BoundContainedType>> pendingActions = new FunctionalList<>();
 		actions.forEach(pendingActions::add);
 
-		// Prepare the new supplier
+		/* Prepare the new supplier. */
 		final Supplier<MappedType> typeSupplier = () -> {
 			IHolder<BoundContainedType> oldHolder = boundHolder;
 
-			// Bound the value if it hasn't been bound
+			/* Bound the value if it hasn't been bound. */
 			if (!holderBound) {
 				oldHolder = oldSupplier.get().unwrap(binder);
 			}
 
+			/* Apply pending actions. */
 			return pendingActions.reduceAux(oldHolder.getValue(), (action, state) -> {
 				return action.apply(state);
 			}, (value) -> mapper.apply(value));
@@ -142,4 +133,4 @@ public class BoundLazy<OldType, BoundContainedType> implements IHolder<BoundCont
 
 		return boundHolder.unwrap(unwrapper);
 	}
-}
\ No newline at end of file
+}
diff --git a/base/src/main/java/bjc/utils/data/internals/BoundLazyPair.java b/base/src/main/java/bjc/utils/data/internals/BoundLazyPair.java
index df6e60b..df2f0d8 100644
--- a/base/src/main/java/bjc/utils/data/internals/BoundLazyPair.java
+++ b/base/src/main/java/bjc/utils/data/internals/BoundLazyPair.java
@@ -9,34 +9,38 @@ import bjc.utils.data.IPair;
 import bjc.utils.data.Identity;
 import bjc.utils.data.LazyPair;
 
-/*
- * Implements a lazy pair that has been bound
+/**
+ * Implements a lazy pair that has been bound.
+ *
+ * @author Ben Culkin
  */
 public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPair<NewLeft, NewRight> {
-	/*
-	 * The supplier of the left value
-	 */
+	/* The supplier of the left value. */
 	private final Supplier<OldLeft> leftSupplier;
-	/*
-	 * The supplier of the right value
-	 */
+	/* The supplier of the right value. */
 	private final Supplier<OldRight> rightSupplier;
 
-	/*
-	 * The binder to transform values
-	 */
+	/* The binder to transform values. */
 	private final BiFunction<OldLeft, OldRight, IPair<NewLeft, NewRight>> binder;
 
-	/*
-	 * The bound pair
-	 */
+	/* The bound pair. */
 	private IPair<NewLeft, NewRight> boundPair;
 
-	/*
-	 * Whether the pair has been bound yet
-	 */
+	/* Whether the pair has been bound yet. */
 	private boolean pairBound;
 
+	/**
+	 * Create a new bound lazy pair.
+	 *
+	 * @param leftSupp
+	 * 	The supplier for the left value.
+	 *
+	 * @param rightSupp
+	 * 	The supplier for the right value.
+	 *
+	 * @param bindr
+	 * 	The function to use to bind the left and right into a new pair.
+	 */
 	public BoundLazyPair(final Supplier<OldLeft> leftSupp, final Supplier<OldRight> rightSupp,
 			final BiFunction<OldLeft, OldRight, IPair<NewLeft, NewRight>> bindr) {
 		leftSupplier = leftSupp;
@@ -50,10 +54,14 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai
 		if (bindr == null) throw new NullPointerException("Binder must not be null");
 
 		final IHolder<IPair<NewLeft, NewRight>> newPair = new Identity<>(boundPair);
-		final IHolder<Boolean> newPairMade = new Identity<>(pairBound);
+		final IHolder<Boolean> newPairMade              = new Identity<>(pairBound);
 
 		final Supplier<NewLeft> leftSupp = () -> {
 			if (!newPairMade.getValue()) {
+				/*
+				 * If the pair hasn't been bound before, bind
+				 * it.
+				 */
 				newPair.replace(binder.apply(leftSupplier.get(), rightSupplier.get()));
 
 				newPairMade.replace(true);
@@ -64,6 +72,10 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai
 
 		final Supplier<NewRight> rightSupp = () -> {
 			if (!newPairMade.getValue()) {
+				/*
+				 * If the pair hasn't been bound before, bind
+				 * it.
+				 */
 				newPair.replace(binder.apply(leftSupplier.get(), rightSupplier.get()));
 
 				newPairMade.replace(true);
@@ -84,6 +96,10 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai
 			IPair<NewLeft, NewRight> newPair = boundPair;
 
 			if (!pairBound) {
+				/*
+				 * If the pair hasn't been bound before, bind
+				 * it.
+				 */
 				newPair = binder.apply(leftSupplier.get(), rightSupplier.get());
 			}
 
@@ -102,6 +118,10 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai
 			IPair<NewLeft, NewRight> newPair = boundPair;
 
 			if (!pairBound) {
+				/*
+				 * If the pair hasn't been bound before, bind
+				 * it.
+				 */
 				newPair = binder.apply(leftSupplier.get(), rightSupplier.get());
 			}
 
@@ -116,16 +136,20 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai
 			final IPair<OtherLeft, OtherRight> otherPair,
 			final BiFunction<NewLeft, OtherLeft, CombinedLeft> leftCombiner,
 			final BiFunction<NewRight, OtherRight, CombinedRight> rightCombiner) {
-		if (otherPair == null)
+		if (otherPair == null) {
 			throw new NullPointerException("Other pair must not be null");
-		else if (leftCombiner == null)
+		} else if (leftCombiner == null) {
 			throw new NullPointerException("Left combiner must not be null");
-		else if (rightCombiner == null) throw new NullPointerException("Right combiner must not be null");
+		} else if (rightCombiner == null) {
+			throw new NullPointerException("Right combiner must not be null");
+		}
 
 		return otherPair.bind((otherLeft, otherRight) -> {
 			return bind((leftVal, rightVal) -> {
-				return new LazyPair<>(leftCombiner.apply(leftVal, otherLeft),
-						rightCombiner.apply(rightVal, otherRight));
+				CombinedLeft  cLeft  = leftCombiner.apply(leftVal, otherLeft);
+				CombinedRight cRight = rightCombiner.apply(rightVal, otherRight);
+
+				return new LazyPair<>(cLeft, cRight);
 			});
 		});
 	}
@@ -182,6 +206,9 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai
 		if (merger == null) throw new NullPointerException("Merger must not be null");
 
 		if (!pairBound) {
+			/*
+			 * If the pair isn't bound yet, bind it.
+			 */
 			boundPair = binder.apply(leftSupplier.get(), rightSupplier.get());
 
 			pairBound = true;
@@ -196,4 +223,4 @@ public class BoundLazyPair<OldLeft, OldRight, NewLeft, NewRight> implements IPai
 
 		return "(un-materialized)";
 	}
-}
\ No newline at end of file
+}
diff --git a/base/src/main/java/bjc/utils/data/internals/BoundListHolder.java b/base/src/main/java/bjc/utils/data/internals/BoundListHolder.java
index f3799fd..8f9e87f 100644
--- a/base/src/main/java/bjc/utils/data/internals/BoundListHolder.java
+++ b/base/src/main/java/bjc/utils/data/internals/BoundListHolder.java
@@ -7,12 +7,21 @@ import bjc.utils.data.IHolder;
 import bjc.utils.data.ListHolder;
 import bjc.utils.funcdata.IList;
 
-/*
- * Holds a list, converted into a holder
+/**
+ * Holds a list, converted into a holder.
+ *
+ * @author Ben Culkin
  */
 public class BoundListHolder<ContainedType> implements IHolder<ContainedType> {
+	/* The list of contained holders. */
 	private final IList<IHolder<ContainedType>> heldHolders;
 
+	/**
+	 * Create a new list of holders.
+	 *
+	 * @param toHold
+	 * 	The list of holders to, well, hold.
+	 */
 	public BoundListHolder(final IList<IHolder<ContainedType>> toHold) {
 		heldHolders = toHold;
 	}
@@ -63,6 +72,10 @@ public class BoundListHolder<ContainedType> implements IHolder<ContainedType> {
 	public <UnwrappedType> UnwrappedType unwrap(final Function<ContainedType, UnwrappedType> unwrapper) {
 		if (unwrapper == null) throw new NullPointerException("Unwrapper must not be null");
 
+		/*
+		 * @NOTE
+		 * 	Is there another way we could want to do this?
+		 */
 		return heldHolders.randItem().unwrap(unwrapper);
 	}
-}
\ No newline at end of file
+}
diff --git a/base/src/main/java/bjc/utils/data/internals/HalfBoundLazyPair.java b/base/src/main/java/bjc/utils/data/internals/HalfBoundLazyPair.java
index 8cac38b..c3606ef 100644
--- a/base/src/main/java/bjc/utils/data/internals/HalfBoundLazyPair.java
+++ b/base/src/main/java/bjc/utils/data/internals/HalfBoundLazyPair.java
@@ -10,16 +10,39 @@ import bjc.utils.data.Identity;
 import bjc.utils.data.LazyPair;
 
 /*
- * A lazy pair, with only one side bound
+ * @NOTE
+ * 	I am not convinced that this code works correctly. Tests should be
+ * 	written to make sure things only ever get instantiated once.
+ *
+ * 	Namely, my main concern is to whether the places that bind the pair
+ * 	without setting pairBound are doing the right thing.
+ */
+/**
+ * A lazy pair, with only one side bound.
+ *
+ * @author Ben Culkin
  */
 public class HalfBoundLazyPair<OldType, NewLeft, NewRight> implements IPair<NewLeft, NewRight> {
+	/* The supplier of the old value. */
 	private final Supplier<OldType> oldSupplier;
 
+	/* The function to transform the old value into a new pair. */
 	private final Function<OldType, IPair<NewLeft, NewRight>> binder;
 
+	/* The new bound pair. */
 	private IPair<NewLeft, NewRight>	boundPair;
+	/* Has the pair been bound yet or not? */
 	private boolean				pairBound;
 
+	/**
+	 * Create a new half-bound lazy pair.
+	 *
+	 * @param oldSupp
+	 * 	The supplier of the old value.
+	 *
+	 * @param bindr
+	 * 	The function to use to create the pair from the old value.
+	 */
 	public HalfBoundLazyPair(final Supplier<OldType> oldSupp,
 			final Function<OldType, IPair<NewLeft, NewRight>> bindr) {
 		oldSupplier = oldSupp;
@@ -34,6 +57,7 @@ public class HalfBoundLazyPair<OldType, NewLeft, NewRight> implements IPair<NewL
 
 		final Supplier<NewLeft> leftSupp = () -> {
 			if (!newPairMade.getValue()) {
+				/* Bind the pair if it hasn't been bound yet. */
 				newPair.replace(binder.apply(oldSupplier.get()));
 				newPairMade.replace(true);
 			}
@@ -43,6 +67,7 @@ public class HalfBoundLazyPair<OldType, NewLeft, NewRight> implements IPair<NewL
 
 		final Supplier<NewRight> rightSupp = () -> {
 			if (!newPairMade.getValue()) {
+				/* Bind the pair if it hasn't been bound yet. */
 				newPair.replace(binder.apply(oldSupplier.get()));
 				newPairMade.replace(true);
 			}
@@ -92,8 +117,10 @@ public class HalfBoundLazyPair<OldType, NewLeft, NewRight> implements IPair<NewL
 			final BiFunction<NewRight, OtherRight, CombinedRight> rightCombiner) {
 		return otherPair.bind((otherLeft, otherRight) -> {
 			return bind((leftVal, rightVal) -> {
-				return new LazyPair<>(leftCombiner.apply(leftVal, otherLeft),
-						rightCombiner.apply(rightVal, otherRight));
+				CombinedLeft  cLeft  = leftCombiner.apply(leftVal, otherLeft);
+				CombinedRight cRight = rightCombiner.apply(rightVal, otherRight);
+
+				return new LazyPair<>(cLeft, cRight);
 			});
 		});
 	}
@@ -146,4 +173,4 @@ public class HalfBoundLazyPair<OldType, NewLeft, NewRight> implements IPair<NewL
 
 		return boundPair.merge(merger);
 	}
-}
\ No newline at end of file
+}
diff --git a/base/src/main/java/bjc/utils/data/internals/WrappedLazy.java b/base/src/main/java/bjc/utils/data/internals/WrappedLazy.java
index 4175724..a5c8130 100644
--- a/base/src/main/java/bjc/utils/data/internals/WrappedLazy.java
+++ b/base/src/main/java/bjc/utils/data/internals/WrappedLazy.java
@@ -6,15 +6,33 @@ import java.util.function.UnaryOperator;
 import bjc.utils.data.IHolder;
 import bjc.utils.data.Lazy;
 
+/**
+ * A wrapped lazy value.
+ *
+ * @author Ben Culkin
+ */
 public class WrappedLazy<ContainedType> implements IHolder<ContainedType> {
+	/* Held value. */
 	private final IHolder<IHolder<ContainedType>> held;
 
+	/**
+	 * Create a new wrapped lazy value.
+	 *
+	 * @param wrappedHolder
+	 * 	The holder to make lazy.
+	 */
 	public WrappedLazy(final IHolder<ContainedType> wrappedHolder) {
 		held = new Lazy<>(wrappedHolder);
 	}
 
-	// This has an extra parameter, because otherwise it erases to the same
-	// as the public one
+	/* 
+	 * This has an extra parameter, because otherwise it erases to the same
+	 * as the public one.
+	 *
+	 * This is a case where reified generics would be useful, because then
+	 * the compiler could know which one we meant without the dummy
+	 * parameter.
+	 */
 	private WrappedLazy(final IHolder<IHolder<ContainedType>> wrappedHolder, final boolean dummy) {
 		held = wrappedHolder;
 	}
diff --git a/base/src/main/java/bjc/utils/data/internals/WrappedOption.java b/base/src/main/java/bjc/utils/data/internals/WrappedOption.java
index 512c699..872295f 100644
--- a/base/src/main/java/bjc/utils/data/internals/WrappedOption.java
+++ b/base/src/main/java/bjc/utils/data/internals/WrappedOption.java
@@ -6,13 +6,30 @@ import java.util.function.UnaryOperator;
 import bjc.utils.data.IHolder;
 import bjc.utils.data.Option;
 
+/**
+ * A wrapped optional value.
+ *
+ * @author Ben Culkin.
+ */
 public class WrappedOption<ContainedType> implements IHolder<ContainedType> {
+	/* The held value. */
 	private final IHolder<IHolder<ContainedType>> held;
 
+	/**
+	 * Create a new wrapped option.
+	 *
+	 * @param seedValue
+	 * 	The value to wrap.
+	 */
 	public WrappedOption(final IHolder<ContainedType> seedValue) {
 		held = new Option<>(seedValue);
 	}
 
+	/*
+	 * The dummy parameter is to ensure the compiler can pick the right
+	 * method, because without this method erases to the same type as the
+	 * public one.
+	 */
 	private WrappedOption(final IHolder<IHolder<ContainedType>> toHold, final boolean dummy) {
 		held = toHold;
 	}