svn commit: r1610502 - /commons/proper/csv/trunk/src/main/java/org/apache/commons/csv/CSVPrinter.java

[br...@apache.org]

Author: britter
Date: Mon Jul 14 19:56:19 2014
New Revision: 1610502

URL: http://svn.apache.org/r1610502
Log:
Document how the pintRecord(s) methods work

Modified:
    commons/proper/csv/trunk/src/main/java/org/apache/commons/csv/CSVPrinter.java

Modified: commons/proper/csv/trunk/src/main/java/org/apache/commons/csv/CSVPrinter.java
URL: http://svn.apache.org/viewvc/commons/proper/csv/trunk/src/main/java/org/apache/commons/csv/CSVPrinter.java?rev=1610502&r1=1610501&r2=1610502&view=diff
==============================================================================
--- commons/proper/csv/trunk/src/main/java/org/apache/commons/csv/CSVPrinter.java (original)
+++ commons/proper/csv/trunk/src/main/java/org/apache/commons/csv/CSVPrinter.java Mon Jul 14 19:56:19 2014
@@ -341,8 +341,11 @@ public final class CSVPrinter implements
     }
 
     /**
-     * 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 final class CSVPrinter implements
     }
 
     /**
-     * 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 final class CSVPrinter implements
     }
 
     /**
-     * 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 final class CSVPrinter implements
     }
 
     /**
-     * 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);