Update documentation

Also, did the same thing for Die I did for DiePool, where I moved the
specific classes to the same file as the interface.

11 files changed, 185 insertions, 142 deletions

diff --git a/dice/src/example/java/bjc/dicelang/neodice/commands/HelpCommand.java b/dice/src/example/java/bjc/dicelang/neodice/commands/HelpCommand.java
index 705745e..c10db4e 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/commands/HelpCommand.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/commands/HelpCommand.java
@@ -7,6 +7,11 @@ import java.util.*;
 import bjc.dicelang.neodice.*;
 import bjc.dicelang.neodice.statements.*;
 
+/**
+ * Diebox help command. Unimplemented as of yet.
+ * @author Ben Culkin
+ *
+ */
 public class HelpCommand implements Command {
 	@Override
 	public StatementValue execute(Iterator<String> words, DieBoxCLI state) {
diff --git a/dice/src/example/java/bjc/dicelang/neodice/commands/LiteralCommand.java b/dice/src/example/java/bjc/dicelang/neodice/commands/LiteralCommand.java
index 9b42b42..b781ae9 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/commands/LiteralCommand.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/commands/LiteralCommand.java
@@ -5,12 +5,28 @@ import java.util.*;
 import bjc.dicelang.neodice.*;
 import bjc.dicelang.neodice.statements.*;
 
+/**
+ * A command that produces a literal statement value.
+ * 
+ * This command will always produce the same statement value, so passing any sort
+ * of mutable statement value to it is asking to be hurt.
+ * 
+ * @author Ben Culkin
+ *
+ */
 public class LiteralCommand implements Command {
 	private final StatementValue value;
 
 	private final String shortHelp;
 	private final String longHelp;
 
+	/**
+	 * Create a new command producing a literal statement value.
+	 * 
+	 * @param value The value this command returns.
+	 * @param shortHelp The short-help (summary) for this command.
+	 * @param longHelp The long-help (description) for this command.
+	 */
 	public LiteralCommand(StatementValue value, String shortHelp, String longHelp) {
 		this.value = value;
 		
diff --git a/dice/src/example/java/bjc/dicelang/neodice/commands/PolyhedralDieCommand.java b/dice/src/example/java/bjc/dicelang/neodice/commands/PolyhedralDieCommand.java
index aad2a24..e0f66b1 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/commands/PolyhedralDieCommand.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/commands/PolyhedralDieCommand.java
@@ -7,6 +7,12 @@ import java.util.*;
 import bjc.dicelang.neodice.*;
 import bjc.dicelang.neodice.statements.*;
 
+/**
+ * A command that produces a polyhedral die.
+ * 
+ * @author Ben Culkin
+ *
+ */
 public class PolyhedralDieCommand implements Command {
 	@Override
 	public StatementValue execute(Iterator<String> words, DieBoxCLI state) {
diff --git a/dice/src/example/java/bjc/dicelang/neodice/commands/RollCommand.java b/dice/src/example/java/bjc/dicelang/neodice/commands/RollCommand.java
index eb8beda..cec7c48 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/commands/RollCommand.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/commands/RollCommand.java
@@ -7,6 +7,12 @@ import java.util.*;
 import bjc.dicelang.neodice.*;
 import bjc.dicelang.neodice.statements.*;
 
+/**
+ * A command that rolls a die or die-pool.
+ * 
+ * @author Ben Culkin
+ *
+ */
 public class RollCommand implements Command {
 	@Override
 	public StatementValue execute(Iterator<String> words, DieBoxCLI state) {
diff --git a/dice/src/example/java/bjc/dicelang/neodice/commands/ShowBindingsCommand.java b/dice/src/example/java/bjc/dicelang/neodice/commands/ShowBindingsCommand.java
index fe2ac89..75811b6 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/commands/ShowBindingsCommand.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/commands/ShowBindingsCommand.java
@@ -7,6 +7,12 @@ import java.util.*;
 import bjc.dicelang.neodice.*;
 import bjc.dicelang.neodice.statements.*;
 
+/**
+ * A command that shows all of the currently bound variables.
+ * 
+ * @author Ben Culkin
+ *
+ */
 public class ShowBindingsCommand implements Command {
   @Override
   public StatementValue execute(Iterator<String> words, DieBoxCLI state) {
diff --git a/dice/src/example/java/bjc/dicelang/neodice/statements/IntegerStatementValue.java b/dice/src/example/java/bjc/dicelang/neodice/statements/IntegerStatementValue.java
index 91e45b6..88508d2 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/statements/IntegerStatementValue.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/statements/IntegerStatementValue.java
@@ -2,9 +2,19 @@ package bjc.dicelang.neodice.statements;
 
 import static bjc.dicelang.neodice.statements.StatementValue.Type.*;
 
+/**
+ * Statement value that represents an integer.
+ * @author Ben Culkin
+ *
+ */
 public class IntegerStatementValue extends StatementValue {
-	public final int value;
+	/** The integer value. */
+    public final int value;
 	
+	/**
+	 * Create an integer statement value.
+	 * @param value The int to use as the value.
+	 */
 	public IntegerStatementValue(int value) {
 		super(INTEGER);
 		
diff --git a/dice/src/example/java/bjc/dicelang/neodice/statements/VoidStatementValue.java b/dice/src/example/java/bjc/dicelang/neodice/statements/VoidStatementValue.java
index 7e437e7..a71d49c 100644
--- a/dice/src/example/java/bjc/dicelang/neodice/statements/VoidStatementValue.java
+++ b/dice/src/example/java/bjc/dicelang/neodice/statements/VoidStatementValue.java
@@ -3,11 +3,13 @@ package bjc.dicelang.neodice.statements;
 import static bjc.dicelang.neodice.statements.StatementValue.Type.*;
 
 /**
+ * The statement value of the null type.
  * @author Ben Culkin
  *
  */
 public class VoidStatementValue extends StatementValue {
-	public static final VoidStatementValue VOID_INST = new VoidStatementValue();
+    /** The singular instance of the null value. */
+    public static final VoidStatementValue VOID_INST = new VoidStatementValue();
 	
 	private VoidStatementValue() {
 		super(VOID);
diff --git a/dice/src/main/java/bjc/dicelang/neodice/Die.java b/dice/src/main/java/bjc/dicelang/neodice/Die.java
index 9d1ac4b..56e4327 100644
--- a/dice/src/main/java/bjc/dicelang/neodice/Die.java
+++ b/dice/src/main/java/bjc/dicelang/neodice/Die.java
@@ -4,7 +4,7 @@ import java.util.*;
 import java.util.function.*;
 import java.util.stream.*;
 
-import bjc.dicelang.neodice.die.*;
+import bjc.esodata.*;
 
 /**
  * Represents a single polyhedral die.
@@ -105,4 +105,128 @@ public interface Die<SideType> {
 	static Die<Integer> polyhedral(int sides) {
 		return new PolyhedralDie(sides);
 	}
+}
+
+class PolyhedralDie implements Die<Integer> {
+    private final int sides;
+
+    public PolyhedralDie(int sides) {
+        this.sides = sides;
+    }
+
+    @Override
+    public Integer roll(Random rng) {
+        // Dice are one-based, not zero-based.
+        return rng.nextInt(sides) + 1;
+    }
+
+    @Override
+    public String toString() {
+        return String.format("d%d", sides);
+    }
+    
+    @Override
+    public int hashCode() {
+        final int prime = 31;
+        int result = 1;
+        result = prime * result + sides;        
+        return result;
+    }
+
+    @Override
+    public boolean equals(Object obj) {
+        if (this == obj)                  return true;
+        if (obj == null)                  return false;
+        if (getClass() != obj.getClass()) return false;
+        
+        PolyhedralDie other = (PolyhedralDie) obj;
+        
+        if (sides != other.sides) return false;
+        else                      return true;
+    }
+}
+
+class RerollDie<SideType> implements Die<SideType> {
+    private final Die<SideType> contained;
+    
+    private final Predicate<SideType>                    condition;
+    private final Function<MinMaxList<SideType>, SideType> chooser;
+    
+    private final Comparator<SideType> comparer;
+    
+    private int limit = Integer.MAX_VALUE;
+    
+    private RerollDie(
+            Comparator<SideType> comparer,
+            Die<SideType> contained,
+            Predicate<SideType> condition,
+            Function<MinMaxList<SideType>, SideType> chooser) {
+        this.comparer = comparer;
+        
+        this.contained = contained;
+        
+        this.condition = condition;
+        this.chooser   = chooser;
+    }
+    
+    private RerollDie(
+            Comparator<SideType> comparer,
+            Die<SideType> contained,
+            Predicate<SideType> condition,
+            Function<MinMaxList<SideType>, SideType> chooser,
+            int limit) {
+        this(comparer, contained, condition, chooser);
+        
+        this.limit = limit;
+    }
+    
+    @Override
+    public SideType roll(Random rng) {
+        SideType roll = contained.roll(rng);
+
+        MinMaxList<SideType> newRolls = new MinMaxList<>(comparer, roll);
+        
+        int rerollCount = 0;
+        while (condition.test(roll) && rerollCount < limit) {
+            roll = contained.roll(rng);
+            newRolls.add(roll);
+            
+            rerollCount += 1;
+        }
+        
+        return chooser.apply(newRolls);
+    }
+
+    public static <Side extends Comparable<Side>> Die<Side> create(
+            Die<Side> contained,
+            Predicate<Side> condition,
+            Function<MinMaxList<Side>, Side> chooser) {
+        return new RerollDie<>(Comparator.naturalOrder(), contained, condition, chooser);
+    }
+    
+    public static <Side extends Comparable<Side>> Die<Side> create(
+            Die<Side> contained,
+            Predicate<Side> condition,
+            Function<MinMaxList<Side>, Side> chooser,
+            int limit) {
+        return new RerollDie<>(Comparator.naturalOrder(), contained, condition, chooser, limit);
+    }
+    
+
+    public static <Side> Die<Side> create(
+            Comparator<Side> comparer,
+            Die<Side> contained,
+            Predicate<Side> condition,
+            Function<MinMaxList<Side>, Side> chooser) {
+        return new RerollDie<>(comparer, contained, condition, chooser);
+    }
+    
+    public static <Side> Die<Side> create(
+            Comparator<Side> comparer,
+            Die<Side> contained,
+            Predicate<Side> condition,
+            Function<MinMaxList<Side>, Side> chooser,
+            int limit) {
+        return new RerollDie<>(comparer, contained, condition, chooser, limit);
+    }
 }
\ No newline at end of file
diff --git a/dice/src/main/java/bjc/dicelang/neodice/DiePool.java b/dice/src/main/java/bjc/dicelang/neodice/DiePool.java
index 4513682..16bec48 100644
--- a/dice/src/main/java/bjc/dicelang/neodice/DiePool.java
+++ b/dice/src/main/java/bjc/dicelang/neodice/DiePool.java
@@ -8,7 +8,8 @@ import java.util.stream.*;
  * Represents a pool of dice.
  * 
  * @author Ben Culkin
- *
+ * 
+ * @param <SideType> The type of the sides of the contained dice.
  */
 @FunctionalInterface
 public interface DiePool<SideType> {
@@ -55,6 +56,7 @@ public interface DiePool<SideType> {
 	 * Returns a version of this die pool which returns its results in sorted
 	 * order.
 	 * 
+	 * @param comparer The comparator to use for the dice.
 	 * @param isDescending True to sort in descending order, false to sort in ascending order.
 	 * 
 	 * @return The die pool, which returns its results in sorted order.
@@ -152,6 +154,7 @@ public interface DiePool<SideType> {
 	/**
 	 * Return a die pool which rolls this one, then drops a number of the lowest values.
 	 * 
+	 * @param comparer The comparer to use for the sides.
 	 * @param number The number of lowest values to drop.
 	 * 
 	 * @return A die pool which has the lowest entries dropped.
@@ -163,6 +166,7 @@ public interface DiePool<SideType> {
 	/**
 	 * Return a die pool which rolls this one, then drops a number of the lowest values.
 	 * 
+	 * @param comparer The comparer to use for the sides.
 	 * @param number The number of lowest values to drop.
 	 * 
 	 * @return A die pool which has the lowest entries dropped.
@@ -174,6 +178,7 @@ public interface DiePool<SideType> {
 	/**
 	 * Return a die pool which rolls this one, then keeps a number of the lowest values.
 	 * 
+	 * @param comparer The comparer to use for the sides.
 	 * @param number The number of lowest values to keep.
 	 * 
 	 * @return A die pool which has the lowest entries kept.
@@ -185,6 +190,7 @@ public interface DiePool<SideType> {
 	/**
 	 * Return a die pool which rolls this one, then keeps a number of the highest values.
 	 * 
+	 * @param comparer The comparer to use for the sides.
 	 * @param number The number of highest values to keep.
 	 * 
 	 * @return A die pool which has the highest entries kept.
diff --git a/dice/src/main/java/bjc/dicelang/neodice/die/PolyhedralDie.java b/dice/src/main/java/bjc/dicelang/neodice/die/PolyhedralDie.java
deleted file mode 100644
index 07ab183..0000000
--- a/dice/src/main/java/bjc/dicelang/neodice/die/PolyhedralDie.java
+++ /dev/null
@@ -1,46 +0,0 @@
-package bjc.dicelang.neodice.die;
-
-import java.util.*;
-
-import bjc.dicelang.neodice.*;
-
-public class PolyhedralDie implements Die<Integer> {
-	private final int sides;
-
-	public PolyhedralDie(int sides) {
-		this.sides = sides;
-	}
-
-	@Override
-	public Integer roll(Random rng) {
-		// Dice are one-based, not zero-based.
-		return rng.nextInt(sides) + 1;
-	}
-
-	@Override
-	public String toString() {
-		return String.format("d%d", sides);
-	}
-	
-	@Override
-	public int hashCode() {
-		final int prime = 31;
-		int result = 1;
-		result = prime * result + sides;		
-		return result;
-	}
-
-	@Override
-	public boolean equals(Object obj) {
-		if (this == obj)                  return true;
-		if (obj == null)                  return false;
-		if (getClass() != obj.getClass()) return false;
-		
-		PolyhedralDie other = (PolyhedralDie) obj;
-		
-		if (sides != other.sides) return false;
-		else                      return true;
-	}
-	
-	
-}
\ No newline at end of file
diff --git a/dice/src/main/java/bjc/dicelang/neodice/die/RerollDie.java b/dice/src/main/java/bjc/dicelang/neodice/die/RerollDie.java
deleted file mode 100644
index 7925c9d..0000000
--- a/dice/src/main/java/bjc/dicelang/neodice/die/RerollDie.java
+++ /dev/null
@@ -1,92 +0,0 @@
-package bjc.dicelang.neodice.die;
-
-import java.util.*;
-import java.util.function.*;
-
-import bjc.dicelang.neodice.*;
-import bjc.esodata.*;
-
-public class RerollDie<SideType> implements Die<SideType> {
-	private final Die<SideType> contained;
-	
-	private final Predicate<SideType>                    condition;
-	private final Function<MinMaxList<SideType>, SideType> chooser;
-	
-	private final Comparator<SideType> comparer;
-	
-	private int limit = Integer.MAX_VALUE;
-	
-	private RerollDie(
-			Comparator<SideType> comparer,
-			Die<SideType> contained,
-			Predicate<SideType> condition,
-			Function<MinMaxList<SideType>, SideType> chooser) {
-		this.comparer = comparer;
-		
-		this.contained = contained;
-		
-		this.condition = condition;
-		this.chooser   = chooser;
-	}
-	
-	private RerollDie(
-			Comparator<SideType> comparer,
-			Die<SideType> contained,
-			Predicate<SideType> condition,
-			Function<MinMaxList<SideType>, SideType> chooser,
-			int limit) {
-		this(comparer, contained, condition, chooser);
-		
-		this.limit = limit;
-	}
-	
-	@Override
-	public SideType roll(Random rng) {
-		SideType roll = contained.roll(rng);
-
-		MinMaxList<SideType> newRolls = new MinMaxList<>(comparer, roll);
-		
-		int rerollCount = 0;
-		while (condition.test(roll) && rerollCount < limit) {
-			roll = contained.roll(rng);
-			newRolls.add(roll);
-			
-			rerollCount += 1;
-		}
-		
-		return chooser.apply(newRolls);
-	}
-
-	public static <Side extends Comparable<Side>> Die<Side> create(
-			Die<Side> contained,
-			Predicate<Side> condition,
-			Function<MinMaxList<Side>, Side> chooser) {
-		return new RerollDie<>(Comparator.naturalOrder(), contained, condition, chooser);
-	}
-	
-	public static <Side extends Comparable<Side>> Die<Side> create(
-			Die<Side> contained,
-			Predicate<Side> condition,
-			Function<MinMaxList<Side>, Side> chooser,
-			int limit) {
-		return new RerollDie<>(Comparator.naturalOrder(), contained, condition, chooser, limit);
-	}
-	
-
-	public static <Side> Die<Side> create(
-			Comparator<Side> comparer,
-			Die<Side> contained,
-			Predicate<Side> condition,
-			Function<MinMaxList<Side>, Side> chooser) {
-		return new RerollDie<Side>(comparer, contained, condition, chooser);
-	}
-	
-	public static <Side> Die<Side> create(
-			Comparator<Side> comparer,
-			Die<Side> contained,
-			Predicate<Side> condition,
-			Function<MinMaxList<Side>, Side> chooser,
-			int limit) {
-		return new RerollDie<Side>(comparer, contained, condition, chooser, limit);
-	}
-}
\ No newline at end of file