Added javadoc

src/main/java/edu/unl/cse/bohn/StringBox.java

@@ -4,6 +4,22 @@
 
 package edu.unl.cse.bohn;
 
+/**
+ * <p>A very simple terminal-based display. Can be used to place arbitrary strings in arbitrary locations in a terminal
+ * window. StringBox will <i>not</i> redraw the screen. Instead, it will produce a string that, when printed, will fill
+ * the screen, causing the screen's previous contents to scroll off of the screen.</p>
+ *
+ * <p>A typical usage is:</p>
+ * <pre><code>
+ *     StringBox stringBox = new StringBox();
+ *     String screen = stringBox
+ *             .placeString(...)
+ *                  ⋮
+ *             .placeString(...)
+ *             .toString();
+ *     System.out.println(screen);
+ * </code></pre>
+ */
 public class StringBox {
     private int maximumWidth;
     private int maximumHeight;
@@ -11,10 +27,31 @@ public class StringBox {
 
     private StringRow[] rows;
 
+    /**
+     * <p>Produces a StringBox suitably-sized for a standard 24x80 terminal. The StringBox will be 23x80; if the string
+     * is printed with <code>System.out.println()</code> then it will leave the cursor on the 24th line, where the
+     * user can enter their input without scrolling the top of the string off the screen.</p>
+     *
+     * <p>Alternatively, you might create a 24x80 StringBox using {@link #StringBox(int, int)}. If the string is printed
+     * with <code>System.out.print()</code> then it will leave the cursor at the end of the 24th line without scrolling
+     * the top of the string off of the screen. This particular style would be useful if you place the prompt on the
+     * 24th line.</p>
+     */
     public StringBox() {
         this(23, 80);    // standard terminal is 24x80, but leave room for the user's input
     }
 
+    /**
+     * <p>Produces an arbitrarily-sized StringBox. The StringBox should be no wider than your terminal and should be
+     * at least one line shorter than your terminal. If the string is printed with <code>System.out.println()</code>
+     * then it will leave the cursor on the last line, where the user can enter their input without scrolling the top
+     * of the string off the screen.</p>
+     *
+     * <p>Alternatively, you might create a StringBox whose height is the height of your terminal. If the string is
+     * printed with <code>System.out.print()</code> then it will leave the cursor at the end of the last line without
+     * scrolling the top of the string off of the screen. This particular style would be useful if you place the
+     * prompt on the last line.</p>
+     */
     public StringBox(int maximumHeight, int maximumWidth) {
         if (maximumHeight > 0 && maximumWidth > 0) {
             this.maximumHeight = maximumHeight;
@@ -30,10 +67,34 @@ public class StringBox {
         }
     }
 
+    /**
+     * <p>Places a string in the StringBox with its upper-left corner in the specified location. If the string
+     * contains multiple lines, each line after the first will be placed in the row subsequent to the previous line,
+     * and the lines will be left-justified. Any portions of the string that would be placed outside the StringBox's
+     * defined boundaries will be silently truncated.</p>
+     *
+     * <p>Equivalent to {@link #placeStringAlignTopLeft(String, int, int)}</p>
+     *
+     * @param string     the string to be placed in the StringBox
+     * @param topRow     the row on which the first line of the string should be placed
+     * @param leftColumn the column in which the first character of each row should be placed
+     * @return the current StringBox object, suitable for chained calls
+     */
     public StringBox placeString(String string, int topRow, int leftColumn) {
         return placeStringAlignTopLeft(string, topRow, leftColumn);
     }
 
+    /**
+     * Places a string in the StringBox with its upper-left corner in the specified location. If the string
+     * contains multiple lines, each line after the first will be placed in the row subsequent to the previous line,
+     * and the lines will be left-justified. Any portions of the string that would be placed outside the StringBox's
+     * defined boundaries will be silently truncated.
+     *
+     * @param string     the string to be placed in the StringBox
+     * @param topRow     the row on which the first line of the string should be placed
+     * @param leftColumn the column in which the first character of each row should be placed
+     * @return the current StringBox object, suitable for chained calls
+     */
     public StringBox placeStringAlignTopLeft(String string, int topRow, int leftColumn) {
         String[] strings = string.split("\n");
         int firstRow = Math.max(topRow, 0);
@@ -46,26 +107,59 @@ public class StringBox {
         return this;
     }
 
+    /**
+     * Places a string in the StringBox with its lower-left corner in the specified location. If the string
+     * contains multiple lines, each line before the last will be placed in the row previous to the subsequent line,
+     * and the lines will be left-justified. Any portions of the string that would be placed outside the StringBox's
+     * defined boundaries will be silently truncated.
+     *
+     * @param string     the string to be placed in the StringBox
+     * @param bottomRow  the row on which the last line of the string should be placed
+     * @param leftColumn the column in which the first character of each row should be placed
+     * @return the current StringBox object, suitable for chained calls
+     */
     public StringBox placeStringAlignBottomLeft(String string, int bottomRow, int leftColumn) {
         String[] strings = string.split("\n");
         return placeStringAlignTopLeft(string, bottomRow - strings.length + 1, leftColumn);
     }
 
-    public StringBox placeStringAlignTopRight(String string, int topRow, int leftColumn) {
+    /**
+     * Places a string in the StringBox with its upper-right corner in the specified location. If the string
+     * contains multiple lines, each line after the first will be placed in the row subsequent to the previous line,
+     * and the lines will be right-justified. Any portions of the string that would be placed outside the StringBox's
+     * defined boundaries will be silently truncated.
+     *
+     * @param string      the string to be placed in the StringBox
+     * @param topRow      the row on which the first line of the string should be placed
+     * @param rightColumn the column in which the last character of each row should be placed
+     * @return the current StringBox object, suitable for chained calls
+     */
+    public StringBox placeStringAlignTopRight(String string, int topRow, int rightColumn) {
         String[] strings = string.split("\n");
         int firstRow = Math.max(topRow, 0);
         int lastRow = Math.min(topRow + strings.length, maximumHeight);
         int offset = -topRow;
         for (int i = firstRow; i < lastRow; i++) {
-            rows[i].placeSubstringAlignRight(strings[i + offset], leftColumn);
+            rows[i].placeSubstringAlignRight(strings[i + offset], rightColumn);
         }
         logicalHeight = Math.max(logicalHeight, lastRow);
         return this;
     }
 
-    public StringBox placeStringAlignBottomRight(String string, int bottomRow, int leftColumn) {
+    /**
+     * Places a string in the StringBox with its lower-right corner in the specified location. If the string
+     * contains multiple lines, each line before the last will be placed in the row previous to the subsequent line,
+     * and the lines will be right-justified. Any portions of the string that would be placed outside the StringBox's
+     * defined boundaries will be silently truncated.
+     *
+     * @param string      the string to be placed in the StringBox
+     * @param bottomRow   the row on which the last line of the string should be placed
+     * @param rightColumn the column in which the first character of each row should be placed
+     * @return the current StringBox object, suitable for chained calls
+     */
+    public StringBox placeStringAlignBottomRight(String string, int bottomRow, int rightColumn) {
         String[] strings = string.split("\n");
-        return placeStringAlignTopRight(string, bottomRow - strings.length + 1, leftColumn);
+        return placeStringAlignTopRight(string, bottomRow - strings.length + 1, rightColumn);
     }
 
     @Override
@@ -73,6 +167,16 @@ public class StringBox {
         return toString(false);
     }
 
+    /**
+     * <p>Generates the string that the client code produced by calling {@link #placeString(String, int, int)} and
+     * its related methods. If this method's argument is <code>true</code>, then any unused lines between the last line
+     * of text and the bottom of the StringBox will be filled with newLines so that when the string is printed, the
+     * previous string will fully scroll off of the screen. If the argument is <code>false</code>, then the returned
+     * string will stop after the last line of text.</p>
+     *
+     * @param padToHeight indicates whether newlines should be placed after the last line of text
+     * @return the string built by calls to {@link #placeString(String, int, int)} and its related methods
+     */
     public String toString(boolean padToHeight) {
         StringBuilder returnString = new StringBuilder(maximumHeight * (maximumWidth + 1));
         if (logicalHeight > 0) {
@@ -89,6 +193,9 @@ public class StringBox {
         return returnString.toString();
     }
 
+    /**
+     * A helper inner class. Client code should not directly access StringRow objects.
+     */
     static class StringRow {
         private StringBuilder stringBuilder;
         private int maximumWidth;