Added javadoc excerpt to README

.gitignore

@@ -3,28 +3,60 @@
 
 # Mac file finder metadata
 .DS_Store
+# Windows file metadata
+._*
+# Thumbnail image caches
+Thumbs.db
+ethumbs.db
 # MS Office temporary file
 ~*
 # Emacs backup file
 *~
 
+# Common
+[Bb]in/
+[Bb]uild/
+[Oo]bj/
+[Oo]ut/
+[Tt]mp/
+[Xx]86/
+[Ii][Aa]32/
+[Xx]64/
+[Xx]86_64/
+[Xx]86-64/
+[Aa]rm/
+[Aa]32/
+[Tt]32/
+[Aa]64/
+*.tmp
+*.bak
+*.bk
+*.swp
+
+# Miscellaneous
+*.gcno
+
 # Java files
 *.class
 javadoc/
 
+# Maven
+target/
+
 # JetBrains (IntelliJ IDEA, PyCharm, etc) files
 .idea/
 cmake-build-*/
-out/
 *.iml
 *.iws
 *.ipr
 
 # Eclipse files
-bin/
 .settings/
-.classpath
 .project
+.classpath
+.buildpath
+.loadpath
+local.properties
 
 # Visual Studio / VS Code files
 .vs*/
@@ -59,6 +91,16 @@ bin/
 *.pidb
 *.svclog
 *.scc
+ipch/
+*.aps
+*.ncb
+*.opensdf
+*.sdf
+*.cachefile
+*.psess
+*.vsp
+*.vspx
+
 
 # Netbeans files
 nbproject/private/
@@ -73,15 +115,3 @@ nb-configuration.xml
 *.xcodeproj/
 xcuserdata/
 .build/
-
-# Maven
-target/
-
-# Miscellaneous
-tmp/
-*.tmp
-*.bak
-*.bk
-*.swp
-*.gcno
-

README.md

@@ -230,5 +230,113 @@ stringBox.placeStringAlignTopLeft("foo\nbar", 2, 10)
 11 |
 ```
 
+##  Javadoc Excerpt
+
+### `public class StringBox`
+
+A very simple terminal-based display. Can be used to place arbitrary strings in arbitrary locations in a terminal
+window. StringBox will *not* 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.
+
+A typical usage is:
+```
+StringBox stringBox = new StringBox();
+String screen = stringBox
+        .placeString(...)
+            ⋮
+        .placeString(...)
+        .toString();
+System.out.println(screen);
+```
+Note that StringBox is *not* robust to hidden characters, such as VT100 escape sequences.
+
+#### `public enum Horizontal`
+
+Horizontal alignment directives
+
+#### `public enum Vertical`
+
+Vertical alignment directives
+
+#### `public StringBox()`
+
+Produces a StringBox suitably-sized for a standard 24×80 terminal. The StringBox will be 23×80; if the string is printed
+with `System.out.println()` 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.
+
+Alternatively, you might create a StringBox using `StringBox(24,80)`. If the string is printed with `System.out.print()`
+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.
+
+ * **See also:** [StringBox(int, int)](#public-stringboxint-boxheight-int-boxwidth)
+
+#### `public StringBox(int boxHeight, int boxWidth)`
+
+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 `System.out.println()` 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.
+
+Alternatively, you might create a StringBox whose height is the height of your terminal. If the string is printed with
+`System.out.print()` 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.
+
+ * **Parameters:**
+   * `boxHeight` — the number of rows in this StringBox
+   * `boxWidth` — the number of columns in this StringBox
+
+#### `public StringBox placeString(String string, int topRow, int 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.
+
+Equivalent to `placeString(string, Vertical.TOP, topRow, Horizontal.LEFT, leftColumn)`.
+
+ * **Parameters:**
+   * `string` — the string to be placed in the StringBox
+   * `topRow` — the row on which the first line of the string should be placed
+   * `leftColumn` — the column in which the first character of each row should be placed
+ * **Returns:** the current StringBox object, suitable for chained calls
+ * **See also:** [placeString(String, Vertical, int, Horizontal, int)](#public-stringbox-placestringstring-string-vertical-verticalalignment-int-verticalposition-horizontal-horizontalalignment-int-horizontalposition)
+ 
+#### `public StringBox placeString(String string, Vertical verticalAlignment, int verticalPosition, Horizontal horizontalAlignment, int horizontalPosition)`
+
+Places a string in the StringBox. If `verticalAlignment` is `TOP` then the string's first line will be in the
+`verticalPosition`'th row, and each subsequent line will be in each subsequent row. If `verticalAlignment` is `BOTTOM`
+then the string's last line will be in the `verticalPosition`'th row, and each preceding line will be in each preceding
+row. If `horizontalAlignment` is `LEFT` then each line will be left-justified to the `horizontalPosition`'th column. If
+`horizontalAlignment` is `RIGHT` then each line will be right-justified to the `horizontalPosition`'th column.
+
+ * **Parameters:**
+   * `string` — the string to be placed in the StringBox
+   * `verticalAlignment` — vertical alignment directive (top/bottom)
+   * `verticalPosition` — the row on which the string should be top/bottom aligned
+   * `horizontalAlignment` — horizontal alignment directive (left/right)
+   * `horizontalPosition` — the column on which the string should be top/bottom aligned
+ * **Returns:** the current StringBox object, suitable for chained calls
+
+#### `@Override public String toString()`
+
+Generates the string that the client code produced by calling {@link #placeString(String, int, int)} and its related
+methods. 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.
+
+Equivalent to `toString(true)`.
+
+ * **Returns:** the string built by calls to {@link #placeString(String, int, int)} and its related methods
+ * **See also:** [toString(boolean)](#public-string-tostringboolean-padtoheight)
+
+#### `public String toString(boolean padToHeight)`
+
+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 `true`, 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 `false`, then the returned string will stop after the last line of text.
+
+ * **Parameters:** `padToHeight` — indicates whether newlines should be placed after the last line of text
+ * **Returns:** the string built by calls to {@link #placeString(String, int, int)} and its related methods
+
+
 ---
 String Box © 2020 Christopher Bohn, bohn@unl.edu

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

@@ -21,6 +21,9 @@ package edu.unl.cse.bohn;
  * </code></pre>
  *
  * <p>Note that StringBox is <i>not</i> robust to hidden characters, such as VT100 escape sequences.</p>
+ *
+ * <p>If found in a project, note that the most-current code can be found in
+ * <a href="https://git.unl.edu/bohn/string_box">its own repository</a>.</p>
  */
 public class StringBox {
     /**
@@ -120,8 +123,8 @@ public class StringBox {
      */
     public StringBox placeString(String string, Vertical verticalAlignment, int verticalPosition,
                                  Horizontal horizontalAlignment, int horizontalPosition) {
-        String[] oneEmptyString = {""};
-        String[] strings = string != null ? string.split(System.lineSeparator()) : oneEmptyString;
+        String[] nullishString = {"null"};
+        String[] strings = string != null ? string.split(System.lineSeparator()) : nullishString;
         // This would benefit from the switch expression in JDK 12/13
         int topRow = verticalAlignment == Vertical.TOP ? verticalPosition :
                   verticalAlignment == Vertical.BOTTOM ? verticalPosition - strings.length + 1 :