CSV-231: Add more documentation to CSVPrinter
Project: http://git-wip-us.apache.org/repos/asf/commons-csv/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-csv/commit/71459b6d Tree: http://git-wip-us.apache.org/repos/asf/commons-csv/tree/71459b6d Diff: http://git-wip-us.apache.org/repos/asf/commons-csv/diff/71459b6d Branch: refs/heads/release Commit: 71459b6d30135723608b06c6ee7a9307b34edaea Parents: e5b2413 Author: Benedikt Ritter <brit...@apache.org> Authored: Fri Aug 31 10:29:12 2018 +0200 Committer: Benedikt Ritter <brit...@apache.org> Committed: Fri Aug 31 10:29:12 2018 +0200 ---------------------------------------------------------------------- src/changes/changes.xml | 1 + .../java/org/apache/commons/csv/CSVPrinter.java | 45 +++++++++++++++++++- 2 files changed, 44 insertions(+), 2 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-csv/blob/71459b6d/src/changes/changes.xml ---------------------------------------------------------------------- diff --git a/src/changes/changes.xml b/src/changes/changes.xml index dd56857..607b979 100644 --- 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> http://git-wip-us.apache.org/repos/asf/commons-csv/blob/71459b6d/src/main/java/org/apache/commons/csv/CSVPrinter.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/csv/CSVPrinter.java b/src/main/java/org/apache/commons/csv/CSVPrinter.java index 3ae5971..ccf4bff 100644 --- 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.sql.SQLException; 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 final class CSVPrinter implements Flushable, Closeable { * 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
