Document how the pintRecord(s) methods work

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/csv/trunk@1610502 13f79535-47bb-0310-9956-ffa450edef68

Author: britter

src/main/java/org/apache/commons/csv/CSVPrinter.java

@@ -341,8 +341,11 @@ public void println() throws IOException {
     }
 
     /**
-     * Prints a single line of delimiter separated values. The values will be quoted if needed. Quotes and newLine
-     * characters will be escaped.
+     * Prints the given values a single record of delimiter separated values followed by the record separator.
+     *
+     * <p>
+     * The values will be quoted if needed. Quotes and newLine characters will be escaped.
+     * </p>
      *
      * @param values
      *            values to output.
@@ -357,8 +360,11 @@ public void printRecord(final Iterable<?> values) throws IOException {
     }
 
     /**
-     * Prints a single line of delimiter separated values. The values will be quoted if needed. Quotes and newLine
-     * characters will be escaped.
+     * Prints the given values a single record of delimiter separated values followed by the record separator.
+     *
+     * <p>
+     * The values will be quoted if needed. Quotes and newLine characters will be escaped.
+     * </p>
      *
      * @param values
      *            values to output.
@@ -373,7 +379,30 @@ public void printRecord(final Object... values) throws IOException {
     }
 
     /**
-     * Prints all the objects in the given collection.
+     * Prints all the objects in the given collection handling nested collections/arrays as records.
+     *
+     * <p>If the given collection only contains simple objects, this method will print a single record like
+     * {@link #printRecord(Iterable)}. If the given collections contains nested collections/arrays those nested elements
+     * will each be printed as records using {@link #printRecord(Object...)}.</p>
+     *
+     * <p>Given the following data structure:</p>
+     * <pre>
+     * <source>
+     * List&lt;String[]&gt; data = ...
+     * data.add(new String[]{ "A", "B", "C" });
+     * data.add(new String[]{ "1", "2", "3" });
+     * data.add(new String[]{ "A1", "B2", "C3" });
+     * </source>
+     * </pre>
+     *
+     * <p>Calling this method will print:</p>
+     * <pre>
+     * <source>
+     * A, B, C
+     * 1, 2, 3
+     * A1, B2, C3
+     * </source>
+     * </pre>
      *
      * @param values
      *            the values to print.
@@ -393,14 +422,37 @@ public void printRecords(final Iterable<?> values) throws IOException {
     }
 
     /**
-     * Prints all the objects in the given array.
+     * Prints all the objects in the given array handling nested collections/arrays as records.
+     *
+     * <p>If the given array only contains simple objects, this method will print a single record like
+     * {@link #printRecord(Object...)}. If the given collections contains nested collections/arrays those nested elements
+     * will each be printed as records using {@link #printRecord(Object...)}.</p>
+     *
+     * <p>Given the following data structure:</p>
+     * <pre>
+     * <source>
+     * String[][] data = new String[3][]
+     * data[0] = String[]{ "A", "B", "C" };
+     * data[1] = new String[]{ "1", "2", "3" };
+     * data[2] = new String[]{ "A1", "B2", "C3" };
+     * </source>
+     * </pre>
+     *
+     * <p>Calling this method will print:</p>
+     * <pre>
+     * <source>
+     * A, B, C
+     * 1, 2, 3
+     * A1, B2, C3
+     * </source>
+     * </pre>
      *
      * @param values
      *            the values to print.
      * @throws IOException
      *             If an I/O error occurs
      */
-    public void printRecords(final Object[] values) throws IOException {
+    public void printRecords(final Object... values) throws IOException {
         for (final Object value : values) {
             if (value instanceof Object[]) {
                 this.printRecord((Object[]) value);