CSV-231: Add more documentation to CSVPrinter

britter · britter · commit 71459b6d3013 · 2018-08-31T10:29:12.000+02:00
diff --git a/src/changes/changes.xml b/src/changes/changes.xml
@@ -39,6 +39,7 @@
   </properties>
   <body>
     <release version="1.6" date="2018-MM-DD" description="Feature and bug fix release">
+      <action issue="CSV-231" type="update" dev="britter">Add more documentation to CSVPrinter.</action>
       <action issue="CSV-217" type="add" dev="ggregory" due-to="Korolyov Alexei">Add autoFlush option for CsvPrinter. PR #24.</action>
       <action issue="CSV-219" type="fix" dev="ggregory" due-to="Zhang Hongda">The behavior of quote char using is not similar as Excel does when the first string contains CJK char(s).</action>
       <action issue="CSV-172" type="fix" dev="ggregory" due-to="Andrew Pennebaker">Don't quote cells just because they have UTF-8 encoded characters.</action>
diff --git a/src/main/java/org/apache/commons/csv/CSVPrinter.java b/src/main/java/org/apache/commons/csv/CSVPrinter.java
@@ -29,7 +29,42 @@
 import java.util.Arrays;
 
 /**
- * Prints values in a CSV format.
+ * Prints values in a {@link CSVFormat CSV format}.
+ *
+ * <p>Values can be appended to the output by calling the {@link #print(Object)} method.
+ * Values are printed according to {@link String#valueOf(Object)}.
+ * To complete a record the {@link #println()} method has to be called.
+ * Comments can be appended by calling {@link #printComment(String)}.
+ * However a comment will only be written to the output if the {@link CSVFormat} supports comments.
+ * </p>
+ *
+ * <p>The printer also supports appending a complete record at once by calling {@link #printRecord(Object...)}
+ * or {@link #printRecord(Iterable)}.
+ * Furthermore {@link #printRecords(Object...)}, {@link #printRecords(Iterable)} and {@link #printRecords(ResultSet)}
+ * methods can be used to print several records at once.
+ * </p>
+ *
+ * <p>Example:</p>
+ *
+ * <pre>
+ * try (CSVPrinter printer = new CSVPrinter(new FileWriter("csv.txt"), CSVFormat.EXCEL)) {
+ *     printer.printRecord("id", "userName", "firstName", "lastName", "birthday");
+ *     printer.printRecord(1, "john73", "John", "Doe", LocalDate.of(1973, 9, 15));
+ *     printer.println();
+ *     printer.printRecord(2, "mary", "Mary", "Meyer", LocalDate.of(1985, 3, 29));
+ * } catch (IOException ex) {
+ *     ex.printStackTrace();
+ * }
+ * </pre>
+ *
+ * <p>This code will write the following to csv.txt:</p>
+ * <pre>
+ * id,userName,firstName,lastName,birthday
+ * 1,john73,John,Doe,1973-09-15
+ *
+ * 2,mary,Mary,Meyer,1985-03-29
+ * </pre>
+ * <p></p>
  */
 public final class CSVPrinter implements Flushable, Closeable {
 
@@ -141,11 +176,17 @@ public void print(final Object value) throws IOException {
      * Prints a comment on a new line among the delimiter separated values.
      *
      * <p>
-     * Comments will always begin on a new line and occupy a least one full line. The character specified to start
+     * Comments will always begin on a new line and occupy at least one full line. The character specified to start
      * comments and a space will be inserted at the beginning of each new line in the comment.
      * </p>
      *
+     * <p>
      * If comments are disabled in the current CSV format this method does nothing.
+     * </p>
+     *
+     * <p>This method detects line breaks inside the comment string and inserts {@link CSVFormat#getRecordSeparator()}
+     * to start a new line of the comment. Note that this might produce unexpected results for formats that do not use
+     * line breaks as record separator.</p>
      *
      * @param comment
      *            the comment to output
