Merge pull request #4 in MFATT/common from pr/add-class-javadoc to master

* commit '3e485f5f6e4cc02aad981c7f3067ba99b0912670':
  Add JavaDoc; expand README content

Author: Babcock, Scott

README.md

@@ -165,25 +165,32 @@ public class OpctConfig extends SettingsCore<OpctConfig.OpctValues> {
 
 ## PathUtils
 
-The **PathUtils** `getNextPath` method provides a method to acquire the next file path in sequence for the specified base name and extension in the indicated target folder.
+The **PathUtils** `getNextPath` method provides a method to acquire the next file path in sequence for the specified base name and extension in the indicated target folder. If the target folder already contains at least one file that matches the specified base name and extension, the algorithm used to select the next path will always return a path whose index is one more than the highest index that currently exists. (If a single file with no index is found, its implied index is 1.)
+
+##### Example usage of `getNextPath`
 
 ```java
+    ...
+    
+    /*
+     * This example gets the next path in sequence for base name `artifact`
+     * and extension `txt` in the TestNG output directory.
+     * 
+     * For purposes of this example, the output directory already contains
+     * the following files: `artifact.txt`, `artifact-3.txt`
+     */
 
-        /*
-         * This example gets the next path in sequence for base name `artifact` and extension `txt` in the TestNG output directory.
-         * 
-         * For purposes of this example, the output directory already contains the following files: `artifact.txt`, `artifact-3.txt`
-         */
+    Path collectionPath = Paths.get(testContext.getOutputDirectory());
+    // => C:\git\my-project\test-output\Default suite
 
-        Path collectionPath = Paths.get(testContext.getOutputDirectory());
-        // => C:\git\my-project\test-output\Default suite
-        
-        Path artifactPath;
-        try {
-            artifactPath = PathUtils.getNextPath(collectionPath, "artifact", "txt");
-            // => C:\git\my-project\test-output\Default suite\artifact-4.txt
-        } catch (IOException e) {
-            provider.getLogger().info("Unable to get output path; no artifact was captured", e);
-            return;
-        }
-```
+    Path artifactPath;
+    try {
+        artifactPath = PathUtils.getNextPath(collectionPath, "artifact", "txt");
+        // => C:\git\my-project\test-output\Default suite\artifact-4.txt
+    } catch (IOException e) {
+        provider.getLogger().info("Unable to get output path; no artifact was captured", e);
+        return;
+    }
+    
+    ...
+```

src/main/java/com/nordstrom/common/file/PathUtils.java

@@ -13,6 +13,40 @@
 import java.util.regex.Pattern;
 import java.util.stream.Stream;
 
+/**
+ * This utility class provides a {@link #getNextPath(Path, String, String) getNextPath} method to acquire the next file
+ * path in sequence for the specified base name and extension in the indicated target folder.  If the target folder
+ * already contains at least one file that matches the specified base name and extension, the algorithm used to select
+ * the next path will always return a path whose index is one more than the highest index that currently exists. (If a
+ * single file with no index is found, its implied index is 1.)
+ * <br><br>
+ * <b>Example usage of {@code getNextPath}</b>
+ * <pre>
+ *     ...
+ *     
+ *     /*
+ *      * This example gets the next path in sequence for base name `artifact`
+ *      * and extension `txt` in the TestNG output directory.
+ *      * 
+ *      * For purposes of this example, the output directory already contains 
+ *      * the following files: `artifact.txt`, `artifact-3.txt`
+ *      *&#47;
+ * 
+ *     Path collectionPath = Paths.get(testContext.getOutputDirectory());
+ *     // => C:\git\my-project\test-output\Default suite
+ * 
+ *     Path artifactPath;
+ *     try {
+ *         artifactPath = PathUtils.getNextPath(collectionPath, "artifact", "txt");
+ *         // => C:\git\my-project\test-output\Default suite\artifact-4.txt
+ *     } catch (IOException e) {
+ *         provider.getLogger().info("Unable to get output path; no artifact was captured", e);
+ *         return;
+ *     }
+ *     
+ *     ...
+ * </pre>
+ */
 public class PathUtils {
 
     private PathUtils() {

src/main/java/com/nordstrom/common/jdbc/DatabaseUtils.java

@@ -43,7 +43,7 @@
  *     sub-configurations or other dynamic data sources (e.g. - web service).</li>
  * </ul>
  * <b>Query Collection Example</b>
- * <p>
+ * <br><br>
  * <pre>
  * public class OpctConfig extends {@code SettingsCore<OpctConfig.OpctValues>} {
  * 
@@ -228,7 +228,7 @@ public static ResultPackage getResultPackage(QueryAPI query, Object... queryArgs
 
     /**
      * Execute the specified query with the supplied arguments, returning a result of the indicated type.
-     * <p>
+     * <br><br>
      * <b>TYPES</b>: Specific result types produce the following behaviors: <ul>
      * <li>'null' - The query is executed as an update operation.</li>
      * <li>{@link ResultPackage} - An object containing the connection, statement, and result set is returned</li>
@@ -265,7 +265,7 @@ private static Object executeOracleQuery(Class<?> resultType, QueryAPI query, Ob
 
     /**
      * Execute the specified query with the supplied arguments, returning a result of the indicated type.
-     * <p>
+     * <br><br>
      * <b>TYPES</b>: Specific result types produce the following behaviors: <ul>
      * <li>'null' - The query is executed as an update operation.</li>
      * <li>{@link ResultPackage} - An object containing the connection, statement, and result set is returned</li>