Add more documentation

Also, changed my mind on the way DiePool and its implementations should
be structured. The implementations go in the die pool file as internal
classes, because nobody should particularly care the specifics about
their die pool, only that it does what it says it should

13 files changed, 332 insertions, 193 deletions

diff --git a/dice/src/example/java/bjc/dicelang/neodice/DieBoxException.java b/dice/src/example/java/bjc/dicelang/neodice/DieBoxException.java
index efa3d54..e1de67e 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/DieBoxException.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/DieBoxException.java
@@ -1,28 +1,60 @@
 package bjc.dicelang.neodice;
 
+/**
+ * The exception thrown when something goes wrong with diebox.
+ * @author Ben Culkin
+ *
+ */
 public class DieBoxException extends RuntimeException {
 	private static final long serialVersionUID = 1851356458656622896L;
 
+	/** Create a new exception */
 	public DieBoxException() {
 		super();
 	}
 	
+	/**
+	 * Create a new exception with a given message.
+	 * 
+	 * @param message The message for the exception.
+	 */
 	public DieBoxException(String message) {
 		super(message);
 	}
 	
+	/**
+	 * Create a new exception with a given formatted message.
+	 * 
+	 * @param format The format string.
+	 * @param args The format arguments.
+	 */
 	public DieBoxException(String format, Object... args) {
 		super(String.format(format, args));
 	}
 	
+	/**
+	 * Create a new diebox exception with a cause.
+	 * @param cause The cause of this exception.
+	 */
 	public DieBoxException(Throwable cause) {
 		super(cause);
 	}
-	
+
+    /**
+     * Create a new diebox exception with a cause and message.
+     * @param cause The cause of this exception.
+     * @param message The message for the exception.
+     */
 	public DieBoxException(Throwable cause, String message) {
 		super(message, cause);
 	}
-	
+
+    /**
+     * Create a new diebox exception with a cause and formatted message.
+     * @param cause The cause of this exception.
+     * @param format The format string.
+     * @param args The format arguments.
+     */
 	public DieBoxException(Throwable cause, String format, Object... args) {
 		super(String.format(format, args), cause);
 	}
diff --git a/dice/src/example/java/bjc/dicelang/neodice/commands/BindCommand.java b/dice/src/example/java/bjc/dicelang/neodice/commands/BindCommand.java
index 5091c4b..8664379 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/commands/BindCommand.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/commands/BindCommand.java
@@ -7,6 +7,11 @@ import java.util.*;
 import bjc.dicelang.neodice.*;
 import bjc.dicelang.neodice.statements.*;
 
+/**
+ * This command binds a name to a variable slot.
+ * @author Ben Culkin
+ *
+ */
 public class BindCommand implements Command {
   @Override
   public StatementValue execute(Iterator<String> words, DieBoxCLI state) {
diff --git a/dice/src/example/java/bjc/dicelang/neodice/statements/ArrayStatementValue.java b/dice/src/example/java/bjc/dicelang/neodice/statements/ArrayStatementValue.java
index 66e14ad..1a54ca5 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/statements/ArrayStatementValue.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/statements/ArrayStatementValue.java
@@ -4,10 +4,24 @@ import static bjc.dicelang.neodice.statements.StatementValue.Type.*;
 
 import java.util.*;
 
+/**
+ * A statement value which represents an array of statement values.
+ * @author Ben Culkin
+ *
+ * @param <ElementType> The contained type of value.
+ */
 public class ArrayStatementValue<ElementType extends StatementValue> extends StatementValue {
-	public final Type          elementType;
+    /** The type of the contained values. */
+    public final Type          elementType;
+    /** The contained values. */
 	public final ElementType[] values;
 	
+	/**
+	 * Create a new array statement value.
+	 * 
+	 * @param elementType The type of the contained values.
+	 * @param values The contained values.
+	 */
 	@SafeVarargs
 	public ArrayStatementValue(Type elementType, ElementType... values) {
 		super(ARRAY);
diff --git a/dice/src/example/java/bjc/dicelang/neodice/statements/BooleanStatementValue.java b/dice/src/example/java/bjc/dicelang/neodice/statements/BooleanStatementValue.java
index ba89893..aef912b 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/statements/BooleanStatementValue.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/statements/BooleanStatementValue.java
@@ -4,10 +4,17 @@ import static bjc.dicelang.neodice.statements.StatementValue.Type.*;
 
 import java.util.*;
 
+/**
+ * Represents the boolean type for diebox.
+ * @author Ben Culkin
+ *
+ */
 public class BooleanStatementValue extends StatementValue {
 	private boolean value;
 	
+	/** The true boolean instance. */
 	public static final BooleanStatementValue TRUE_INST  = new BooleanStatementValue(true);
+	/** The false boolean instance. */
 	public static final BooleanStatementValue FALSE_INST = new BooleanStatementValue(false);
 	
 	private BooleanStatementValue(boolean value) {
diff --git a/dice/src/example/java/bjc/dicelang/neodice/statements/DiePoolStatementValue.java b/dice/src/example/java/bjc/dicelang/neodice/statements/DiePoolStatementValue.java
index 8d7c1f4..114475c 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/statements/DiePoolStatementValue.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/statements/DiePoolStatementValue.java
@@ -6,10 +6,23 @@ import java.util.*;
 
 import bjc.dicelang.neodice.*;
 
+/**
+ * A StatementValue that represesnts a die pool
+ * @author Ben Culkin
+ *
+ */
 public class DiePoolStatementValue extends StatementValue {
+    /** The type of the contained value. */
 	public final Type elementType;
+	/** The die pool itself. */
 	public final DiePool<StatementValue> value;
 	
+	/**
+	 * Create a new diepool value.
+	 * 
+	 * @param elementType The contained type.
+	 * @param value The die pool itself.
+	 */
 	public DiePoolStatementValue(Type elementType, DiePool<StatementValue> value) {
 		super(DIEPOOL);
 		
diff --git a/dice/src/example/java/bjc/dicelang/neodice/statements/DieStatementValue.java b/dice/src/example/java/bjc/dicelang/neodice/statements/DieStatementValue.java
index f9a8d1e..5662a59 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/statements/DieStatementValue.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/statements/DieStatementValue.java
@@ -6,10 +6,23 @@ import java.util.*;
 
 import bjc.dicelang.neodice.*;
 
+/**
+ * A StatementValue that represents a die.
+ * @author Ben Culkin
+ *
+ */
 public class DieStatementValue extends StatementValue {
+    /** The type of values this die rolls. */
 	public final Type sideType;
+	/** The die itself. */
 	public final Die<StatementValue> value;
 	
+	/**
+	 * Create a new die StatementValue.
+	 * 
+	 * @param sideType The type of value this die rolls.
+	 * @param value The die itself.
+	 */
 	public DieStatementValue(Type sideType, Die<StatementValue> value) {
 		super(DIE);
 		
diff --git a/dice/src/example/java/bjc/dicelang/neodice/statements/StatementValue.java b/dice/src/example/java/bjc/dicelang/neodice/statements/StatementValue.java
index de796e5..d804a10 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/statements/StatementValue.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/statements/StatementValue.java
@@ -2,20 +2,41 @@ package bjc.dicelang.neodice.statements;
 
 import java.util.*;
 
+/**
+ * Represents a value for diebox, as a base class.
+ * @author Ben Culkin
+ *
+ */
 public abstract class StatementValue {
+    /**
+     * The type of the value.
+     * @author Ben Culkin
+     *
+     */
 	public static enum Type {
+	    /** The 'void' value. There is only one value of this type. */
 		VOID,
+		/** The 'boolean' type. There is one true value, and one false value. */
 		BOOLEAN,
+		/** Represents an integer. */
 		INTEGER,
 		
+		/** Represents a single die. */
 		DIE,
+		/** Represents a pool of dice. */
 		DIEPOOL,
 		
+		/** Represents an array of some type. */
 		ARRAY,
 	}
 	
+	/** The type of this value. */
 	public final Type type;
 	
+	/**
+	 * Create a new statement value.
+	 * @param type The type of the value.
+	 */
 	protected StatementValue(Type type) {
 		this.type = type;
 	}
diff --git a/dice/src/main/java/bjc/dicelang/neodice/Die.java b/dice/src/main/java/bjc/dicelang/neodice/Die.java
index 910d173..9d1ac4b 100644
--- a/dice/src/main/java/bjc/dicelang/neodice/Die.java
+++ b/dice/src/main/java/bjc/dicelang/neodice/Die.java
@@ -5,11 +5,12 @@ import java.util.function.*;
 import java.util.stream.*;
 
 import bjc.dicelang.neodice.die.*;
-import bjc.dicelang.neodice.diepool.*;
 
 /**
  * Represents a single polyhedral die.
  * @author Ben Culkin
+ * 
+ * @param <SideType> The type of value represented by this die.
  *
  */
 @FunctionalInterface
@@ -40,6 +41,7 @@ public interface Die<SideType> {
 	/**
 	 * Returns a die which will reroll this die as long as the provided condition is true.
 	 * 
+     * @param comparer The thing to use to compare die values.
 	 * @param condition The condition to reroll the die on.
 	 * 
 	 * @return A die that rerolls when the given condition is met.
@@ -55,6 +57,7 @@ public interface Die<SideType> {
 	 * Returns a die which will reroll this die up to a specified number of times,
 	 * as long as the provided condition is true.
 	 * 
+	 * @param comparer The thing to use to compare die values.
 	 * @param condition The condition to reroll the die on.
 	 * @param limit The maximum number of times to reroll the die.
 	 * 
@@ -79,6 +82,15 @@ public interface Die<SideType> {
 		return Stream.generate(() -> this.roll(rng));
 	}
 	
+	/**
+	 * Create a new transforming die.
+	 * 
+	 * @param <NewType> The new type of the die.
+	 * 
+	 * @param mapper The function to use for mapping.
+	 * 
+	 * @return A die that transforms with the given mapping.
+	 */
 	default <NewType> Die<NewType> transform(Function<SideType, NewType> mapper) {
 		return (rng) -> mapper.apply(this.roll(rng));
 	}
diff --git a/dice/src/main/java/bjc/dicelang/neodice/DiePool.java b/dice/src/main/java/bjc/dicelang/neodice/DiePool.java
index e3a5782..4513682 100644
--- a/dice/src/main/java/bjc/dicelang/neodice/DiePool.java
+++ b/dice/src/main/java/bjc/dicelang/neodice/DiePool.java
@@ -4,8 +4,6 @@ import java.util.*;
 import java.util.function.*;
 import java.util.stream.*;
 
-import bjc.dicelang.neodice.diepool.*;
-
 /**
  * Represents a pool of dice.
  * 
@@ -211,6 +209,8 @@ public interface DiePool<SideType> {
 	/**
 	 * Create a die pool containing the provided dice.
 	 * 
+	 * @param <Side> The type of the sides.
+	 * 
 	 * @param dice The dice to put into the pool.
 	 * 
 	 * @return A pool which contains the provided dice.
@@ -219,4 +219,213 @@ public interface DiePool<SideType> {
 	static <Side> DiePool<Side> containing(Die<Side>... dice) {
 		return new FixedDiePool<>(dice);
 	}
+	
+	/**
+	 * Create an expanding die pool
+	 * 
+	 * @param <Side> The type of the sides.
+	 * 
+	 * @param contained The contained die.
+	 * @param expander The expanding function.
+	 * 
+	 * @return A die pool that expands the result given the provided function.
+	 */
+	static <Side> DiePool<Side> expanding(Die<Side> contained,
+	        BiFunction<Die<Side>, Random, Stream<Side>> expander)
+	{
+	    return new ExpandDiePool<>(contained, expander);
+	}
+}
+
+/**
+ * A die pool that can expand dice.
+ * @author Ben Culkin
+ *
+ * @param <SideType> The type the die uses.
+ */
+class ExpandDiePool<SideType> implements DiePool<SideType> {
+    private final Die<SideType> contained;
+    
+    private final BiFunction<Die<SideType>, Random, Stream<SideType>> expander;
+
+    /**
+     * Create a new expanding die pool.
+     * 
+     * @param contained The die to expand.
+     * @param expander The function to use for expanding.
+     */
+    public ExpandDiePool(Die<SideType> contained,
+            BiFunction<Die<SideType>, Random, Stream<SideType>> expander) {
+        this.contained = contained;
+        this.expander = expander;
+    }
+
+    @Override
+    public Stream<SideType> roll(Random rng) {
+        return expander.apply(contained, rng);
+    }
+    
+    @Override
+    public List<Die<SideType>> contained()
+    {
+        return Arrays.asList(contained);
+    }
+}
+
+/**
+ * A die pool that has a fixed size.
+ * 
+ * @author Ben Culkin
+ *
+ * @param <SideType> The type of the sides of the dice.
+ */
+class FixedDiePool<SideType> implements DiePool<SideType> {
+    private final List<Die<SideType>> dice;
+
+    /**
+     * Create a new fixed dice pool.
+     * @param dice The dice to put into the pool.
+     */
+    public FixedDiePool(List<Die<SideType>> dice) {
+        this.dice = dice;
+    }
+    
+    /**
+     * Create a new fixed dice pool from an array of dice.
+     * @param dice The dice to put into the pool.
+     */
+    @SafeVarargs
+    public FixedDiePool(Die<SideType>...dice) {
+        this.dice = new ArrayList<>(dice.length);
+        for (Die<SideType> die : dice) {
+            this.dice.add(die);
+        }
+    }
+
+    @Override
+    public Stream<SideType> roll(Random rng) {
+        return dice.stream().map((die) -> die.roll(rng));
+    }
+
+    @Override
+    public List<Die<SideType>> contained() {
+        return dice;
+    }
+
+    
+    @Override
+    public String toString() {
+        return dice.stream()
+            .map(Die<SideType>::toString)
+            .collect(Collectors.joining(", "));
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(dice);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj)                  return true;
+        if (obj == null)                  return false;
+        if (getClass() != obj.getClass()) return false;
+    
+        FixedDiePool<?> other = (FixedDiePool<?>) obj;
+        
+        return Objects.equals(dice, other.dice);
+    }
+}
+
+class TimesDiePool<SideType> implements DiePool<SideType> {
+    private final Die<SideType> contained;
+    private final int numDice;
+
+    public TimesDiePool(Die<SideType> contained, int numDice) {
+        this.contained = contained;
+        this.numDice = numDice;
+    }
+
+    @Override
+    public Stream<SideType> roll(Random rng) {
+        return Stream.generate(() -> contained.roll(rng))
+            .limit(numDice);
+    }
+    
+    @Override
+    public List<Die<SideType>> contained() {
+        List<Die<SideType>> results = new ArrayList<>(numDice);
+        
+        for (int index = 0; index < numDice; index++) {
+            results.add(contained);
+        }
+        
+        return results;
+    }
+
+    @Override
+    public String toString() {
+        return String.format("%d%s", numDice, contained);
+    }
+    
+    @Override
+    public int hashCode() {
+        return Objects.hash(contained, numDice);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj)                  return true;
+        if (obj == null)                  return false;
+        if (getClass() != obj.getClass()) return false;
+        
+        TimesDiePool<?> other = (TimesDiePool<?>) obj;
+    
+        return Objects.equals(contained, other.contained) && numDice == other.numDice;
+    }
+}
+
+class TransformDiePool<SideType> implements DiePool<SideType> {
+    private final DiePool<SideType> contained;
+    
+    private UnaryOperator<Stream<SideType>> transform;
+
+    public TransformDiePool(DiePool<SideType> contained,
+            UnaryOperator<Stream<SideType>> transform) {
+        super();
+        this.contained = contained;
+        this.transform = transform;
+    }
+
+    @Override
+    public Stream<SideType> roll(Random rng) {
+        return transform.apply(contained.roll(rng));
+    }
+    
+    @Override
+    public List<Die<SideType>> contained() {
+        return contained.contained();
+    }
+
+    @Override
+    public int hashCode() {
+        return Objects.hash(contained, transform);
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj)                  return true;
+        if (obj == null)                  return false;
+        if (getClass() != obj.getClass()) return false;
+    
+        TransformDiePool<?> other = (TransformDiePool<?>) obj;
+        
+        return Objects.equals(contained, other.contained)
+                && Objects.equals(transform, other.transform);
+    }
+    
+    @Override
+    public String toString() {
+        return contained.toString() + "(transformed)";
+    }
 }
\ No newline at end of file
diff --git a/dice/src/main/java/bjc/dicelang/neodice/diepool/ExpandDiePool.java b/dice/src/main/java/bjc/dicelang/neodice/diepool/ExpandDiePool.java
deleted file mode 100644
index 97acc79..0000000
--- a/dice/src/main/java/bjc/dicelang/neodice/diepool/ExpandDiePool.java
+++ /dev/null
@@ -1,25 +0,0 @@
-package bjc.dicelang.neodice.diepool;
-
-import java.util.*;
-import java.util.function.*;
-import java.util.stream.*;
-
-import bjc.dicelang.neodice.*;
-
-public class ExpandDiePool<SideType> implements DiePool<SideType> {
-	private final Die<SideType> contained;
-	
-	private final BiFunction<Die<SideType>, Random, Stream<SideType>> expander;
-
-	public ExpandDiePool(Die<SideType> contained,
-			BiFunction<Die<SideType>, Random, Stream<SideType>> expander) {
-		this.contained = contained;
-		this.expander = expander;
-	}
-
-
-	@Override
-	public Stream<SideType> roll(Random rng) {
-		return expander.apply(contained, rng);
-	}
-}
diff --git a/dice/src/main/java/bjc/dicelang/neodice/diepool/FixedDiePool.java b/dice/src/main/java/bjc/dicelang/neodice/diepool/FixedDiePool.java
deleted file mode 100644
index 4950407..0000000
--- a/dice/src/main/java/bjc/dicelang/neodice/diepool/FixedDiePool.java
+++ /dev/null
@@ -1,56 +0,0 @@
-package bjc.dicelang.neodice.diepool;
-
-import java.util.*;
-import java.util.stream.*;
-
-import bjc.dicelang.neodice.*;
-
-public class FixedDiePool<SideType> implements DiePool<SideType> {
-	private final List<Die<SideType>> dice;
-
-	public FixedDiePool(List<Die<SideType>> dice) {
-		this.dice = dice;
-	}
-	
-	@SafeVarargs
-	public FixedDiePool(Die<SideType>...dice) {
-		this.dice = new ArrayList<>(dice.length);
-		for (Die<SideType> die : dice) {
-			this.dice.add(die);
-		}
-	}
-
-	@Override
-	public Stream<SideType> roll(Random rng) {
-		return dice.stream().map((die) -> die.roll(rng));
-	}
-
-	@Override
-	public List<Die<SideType>> contained() {
-		return dice;
-	}
-
-	
-	@Override
-	public String toString() {
-		return dice.stream()
-			.map(Die<SideType>::toString)
-			.collect(Collectors.joining(", "));
-	}
-
-	@Override
-	public int hashCode() {
-		return Objects.hash(dice);
-	}
-
-	@Override
-	public boolean equals(Object obj) {
-		if (this == obj)                  return true;
-		if (obj == null)                  return false;
-		if (getClass() != obj.getClass()) return false;
-	
-		FixedDiePool<?> other = (FixedDiePool<?>) obj;
-		
-		return Objects.equals(dice, other.dice);
-	}
-}
\ No newline at end of file
diff --git a/dice/src/main/java/bjc/dicelang/neodice/diepool/TimesDiePool.java b/dice/src/main/java/bjc/dicelang/neodice/diepool/TimesDiePool.java
deleted file mode 100644
index e039e47..0000000
--- a/dice/src/main/java/bjc/dicelang/neodice/diepool/TimesDiePool.java
+++ /dev/null
@@ -1,54 +0,0 @@
-package bjc.dicelang.neodice.diepool;
-
-import java.util.*;
-import java.util.stream.*;
-
-import bjc.dicelang.neodice.*;
-
-public class TimesDiePool<SideType> implements DiePool<SideType> {
-	private final Die<SideType> contained;
-	private final int numDice;
-
-	public TimesDiePool(Die<SideType> contained, int numDice) {
-		this.contained = contained;
-		this.numDice = numDice;
-	}
-
-	@Override
-	public Stream<SideType> roll(Random rng) {
-		return Stream.generate(() -> contained.roll(rng))
-			.limit(numDice);
-	}
-	
-	@Override
-	public List<Die<SideType>> contained() {
-		List<Die<SideType>> results = new ArrayList<>(numDice);
-		
-		for (int index = 0; index < numDice; index++) {
-			results.add(contained);
-		}
-		
-		return results;
-	}
-
-	@Override
-	public String toString() {
-		return String.format("%d%s", numDice, contained);
-	}
-	
-	@Override
-	public int hashCode() {
-		return Objects.hash(contained, numDice);
-	}
-
-	@Override
-	public boolean equals(Object obj) {
-		if (this == obj)                  return true;
-		if (obj == null)                  return false;
-		if (getClass() != obj.getClass()) return false;
-		
-		TimesDiePool<?> other = (TimesDiePool<?>) obj;
-	
-		return Objects.equals(contained, other.contained) && numDice == other.numDice;
-	}
-}
\ No newline at end of file
diff --git a/dice/src/main/java/bjc/dicelang/neodice/diepool/TransformDiePool.java b/dice/src/main/java/bjc/dicelang/neodice/diepool/TransformDiePool.java
deleted file mode 100644
index 80b563f..0000000
--- a/dice/src/main/java/bjc/dicelang/neodice/diepool/TransformDiePool.java
+++ /dev/null
@@ -1,52 +0,0 @@
-package bjc.dicelang.neodice.diepool;
-
-import java.util.*;
-import java.util.function.*;
-import java.util.stream.*;
-
-import bjc.dicelang.neodice.*;
-
-public class TransformDiePool<SideType> implements DiePool<SideType> {
-	private final DiePool<SideType> contained;
-	
-	private UnaryOperator<Stream<SideType>> transform;
-
-	public TransformDiePool(DiePool<SideType> contained,
-			UnaryOperator<Stream<SideType>> transform) {
-		super();
-		this.contained = contained;
-		this.transform = transform;
-	}
-
-	@Override
-	public Stream<SideType> roll(Random rng) {
-		return transform.apply(contained.roll(rng));
-	}
-	
-	@Override
-	public List<Die<SideType>> contained() {
-		return contained.contained();
-	}
-
-	@Override
-	public int hashCode() {
-		return Objects.hash(contained, transform);
-	}
-
-	@Override
-	public boolean equals(Object obj) {
-		if (this == obj)                  return true;
-		if (obj == null)                  return false;
-		if (getClass() != obj.getClass()) return false;
-	
-		TransformDiePool<?> other = (TransformDiePool<?>) obj;
-		
-		return Objects.equals(contained, other.contained)
-				&& Objects.equals(transform, other.transform);
-	}
-	
-	@Override
-	public String toString() {
-		return contained.toString() + "(transformed)";
-	}
-}