#18 Update current README and javadocs

Author: cpointe-ibllanos

README.md

@@ -52,6 +52,9 @@ public class FooToBarMigration extends AbstractMigration {
 The following Java classes in `org.technologybrewery.baton.util` can be leveraged to easily implement common migration logic into your extension:
 * `CommonUtils`
 * `FileUtils`
+* `pom.PomHelper`
+* `pom.PomModifications`
+* `pom.LocationAwareMavenReader`
 
 ### Configure Baton to use the migration
 With a migration to apply, we both configure and tailor that use through a simple json file.  This file can live anywhere

baton-maven-plugin/src/main/java/org/technologybrewery/baton/util/pom/PomHelper.java

@@ -17,13 +17,17 @@
 import java.nio.file.Paths;
 import java.nio.file.StandardCopyOption;
 
+/**
+ * Generalized static utilities for assisting with altering Maven POM files.
+ */
 public final class PomHelper {
 
     private PomHelper(){
     }
 
     /**
      * Helper function to construct a Model of a pom file.
+     *
      * @param file File object representing a pom file.
      * @return the constructed Model.
      */
@@ -40,6 +44,7 @@ public static Model getLocationAnnotatedModel(File file) {
 
     /**
      * Writes a finalized set of modifications back to a pom file.
+     *
      * @param file The original pom file.
      * @param modifications Finalized set of modifications.
      * @return true iff the write operation completes successfully.
@@ -68,7 +73,15 @@ public static boolean writeModifications(File file, PomModifications.Final modif
         return true;
     }
 
-    public static InputLocation incrementColumn(InputLocation location, int i) {
+    /**
+     * Shifts the given column index for a given InputLocation type by a given amount.
+     *
+     * @param location the initial location to be updated with a new column index as a InputLocation.
+     * @param columnIndexShift number of column indexes to move by represented as a signed integer.
+     * @return a new InputLocation type with an updated column index.
+     * @see org.apache.maven.model.InputLocation
+     */
+    public static InputLocation incrementColumn(InputLocation location, int columnIndexShift) {
         return new InputLocation(location.getLineNumber(), location.getColumnNumber() + i, location.getSource());
     }
 }

baton-maven-plugin/src/main/java/org/technologybrewery/baton/util/pom/PomModifications.java

@@ -17,14 +17,31 @@
  */
 public final class PomModifications extends TreeSet<PomModifications.Modification> {
 
+    /**
+     * Returns an instance of the Final class configure with an iterable of all loaded POM file modifications.
+     *
+     * @see org.technologybrewery.baton.util.pom.PomModifications.Final
+     */
     public Final finalizeMods() {
         return new Final(iterator());
     }
 
+    /**
+     * A class to iteratively apply a series of POM file modifications.
+     *
+     * @see org.technologybrewery.baton.util.pom.PomModifications.Modification
+     */
     public static class Final {
         private Iterator<Modification> iterator;
         private Modification next;
 
+        /**
+         * Constructor that initializes a series of POM file modifications passed in as an Iterator of the
+         * internally defined Modification class.
+         *
+         * @param iterator A given Iterator of the type Modification.
+         * @see org.technologybrewery.baton.util.pom.PomModifications.Modification
+         */
         private Final(Iterator<Modification> iterator) {
             this.iterator = iterator;
             next = iterator.next();
@@ -38,11 +55,11 @@ public boolean appliesTo(int lineNumber) {
         /**
          * Applies the next modification to the input reader, writing the result to the output writer.
          *
-         * @param in the input reader
-         * @param out the output writer
-         * @param line the current line of the input reader
-         * @return the line number of `in` after the modification has been applied (changes iff the input reader was advanced)
-         * @throws IOException if an I/O error occurs
+         * @param in the input reader.
+         * @param out the output writer.
+         * @param line the current line of the input reader.
+         * @return the line number of `in` after the modification has been applied (changes iff the input reader was advanced).
+         * @throws IOException if an I/O error occurs.
          */
         public int apply(BufferedReader in, Writer out, String line) throws IOException {
             int newInputLine = next.apply(in, out, line);
@@ -55,9 +72,19 @@ public int apply(BufferedReader in, Writer out, String line) throws IOException
         }
     }
 
+    /**
+     * The abstract class by which all POM file modifications inherit from.
+     */
     public static abstract class Modification implements Comparable<Modification> {
         private final InputLocation start;
 
+        /**
+         * The constructor accepts an InputLocation type representing the line and column of the file
+         * where modifications will start being applied.
+         *
+         * @param start the location to begin modifying the content.
+         * @see org.apache.maven.model.InputLocation
+         */
         public Modification(InputLocation start) {
             this.start = start;
         }
@@ -85,6 +112,13 @@ public int compareTo(Modification o) {
     public static class Deletion extends Modification {
         private final InputLocation end;
 
+        /**
+         * Constructor to delete content between the given start and end parameters.
+         *
+         * @param start the location to begin deleting POM file content (inclusive).
+         * @param end the location to stop deleting POM file content (exclusive).
+         * @see org.apache.maven.model.InputLocation
+         */
         public Deletion(InputLocation start, InputLocation end) {
             super(start);
             this.end = end;
@@ -125,9 +159,12 @@ public static class Insertion extends Modification {
         private final int currentIndent;
 
         /**
-         * @param start the location to insert the content (will insert before the existing content on that line)
-         * @param currentIndent the indent level of the current content on the line
-         * @param contentProducer a function that produces the content to insert, given a one-level indent string
+         * Constructor to insert content before the given start existing content on the given start index.
+         *
+         * @param start the location to insert the content (before the existing content on that line).
+         * @param currentIndent the indent level of the current content on the line.
+         * @param contentProducer a function that produces the content to insert, given a one-level indent string.
+         * @see org.apache.maven.model.InputLocation
          */
         public Insertion(InputLocation start, int currentIndent, Function<String,String> contentProducer) {
             super(start);
@@ -156,9 +193,9 @@ public static class Replacement extends Modification {
         /**
          * Constructor for replacing content within a single line.
          *
-         * @param start the location to insert the new content
-         * @param end the location to skip to, existing content between start and end will be deleted
-         * @param content the new content
+         * @param start the location to insert the new content.
+         * @param end the location to skip to, existing content between start and end will be deleted.
+         * @param content the new content.
          */
         public Replacement(InputLocation start, InputLocation end, String content) {
             this(start, end, 0, l -> content);
@@ -167,10 +204,10 @@ public Replacement(InputLocation start, InputLocation end, String content) {
         /**
          * Constructor for multi-line replacements.
          *
-         * @param start the location to insert the new content
-         * @param end the location to skip to, existing content between start and end will be deleted
-         * @param indentLvl the indent level of the current content on the line
-         * @param contentProducer a function that produces the content to insert, given a one-level indent string
+         * @param start the location to insert the new content.
+         * @param end the location to skip to, existing content between start and end will be deleted.
+         * @param indentLvl the indent level of the current content on the line.
+         * @param contentProducer a function that produces the content to insert, given a one-level indent string.
          */
         public Replacement(InputLocation start, InputLocation end, int indentLvl, Function<String,String> contentProducer) {
             super(start);