svn commit: r1522836 - /commons/proper/csv/trunk/src/main/java/org/apache/commons/csv/CSVParser.java

[britter]

Author: britter
Date: Fri Sep 13 09:44:55 2013
New Revision: 1522836

URL: http://svn.apache.org/r1522836
Log:
CSVParser JavaDoc should be about using the CSVParser and not how to customize 
CSVFormats. Customizing CSVFormats is subject of CSVFormat JavaDoc.

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

Modified: 
commons/proper/csv/trunk/src/main/java/org/apache/commons/csv/CSVParser.java
URL: 
http://svn.apache.org/viewvc/commons/proper/csv/trunk/src/main/java/org/apache/commons/csv/CSVParser.java?rev=1522836&r1=1522835&r2=1522836&view=diff
==============================================================================
--- 
commons/proper/csv/trunk/src/main/java/org/apache/commons/csv/CSVParser.java 
(original)
+++ 
commons/proper/csv/trunk/src/main/java/org/apache/commons/csv/CSVParser.java 
Fri Sep 13 09:44:55 2013
@@ -41,6 +41,8 @@ import java.util.NoSuchElementException;
  * Because CSV appears in many different dialects, the parser supports many 
formats by allowing the
  * specification of a {@link CSVFormat}.
  *
+ * The parser works record wise. It is not possible to go back, once a record 
has been parsed from the input stream.
+ *
  * <h4>Creating instances</h4>
  * There are several static factory methods that can be used to create 
instances for various types of resources:
  * <p>
@@ -56,33 +58,38 @@ import java.util.NoSuchElementException;
  *
  * <h4>Parsing record wise</h4>
  * <p>
- * To parse a CSV input with tabs as separators, '"' (double-quote) as an 
optional value encapsulator, and comments
- * starting with '#', you write:
+ * To parse a CSV input from a file, you write:
  * </p>
  *
  * <pre>
- * Reader in = new StringReader(&quot;a\tb\nc\td&quot;);
- * Iterable&lt;CSVRecord&gt; parser = CSVFormat.DEFAULT
- *     .withCommentStart('#')
- *     .withDelimiter('\t')
- *     .withQuoteChar('"').parse(in);
- *  for (CSVRecord csvRecord : parse) {
+ * File csvData = new File(&quot;/path/to/csv&quot;);
+ * CSVParser parser = CSVParser.parse(csvData, CSVFormat.RFC4180);
+ * for (CSVRecord csvRecord : parser) {
  *     ...
- *  }
+ * }
  * </pre>
  *
  * <p>
- * To parse CSV input in a given format like Excel, you write:
+ * This will read the parse the contents of the file using the
+ * <a href="http://tools.ietf.org/html/rfc4180"; target="_blank">RFC 4180</a> 
format.
+ * </p>
+ *
+ * <p>
+ * To parse CSV input in a format like Excel, you write:
  * </p>
  *
  * <pre>
- * Reader in = new StringReader("a;b\nc;d");
- * Iterable&lt;CSVRecord&gt; parser = CSVFormat.EXCEL.parse(in);
- * for (CSVRecord record : parser) {
+ * CSVParser parser = CSVParser.parse(csvData, CSVFormat.EXCEL);
+ * for (CSVRecord csvRecord : parser) {
  *     ...
  * }
  * </pre>
  *
+ * <p>
+ * If the predefined formats don't match the format at hands, custom formats 
can be defined. More information about
+ * customising CSVFormats is available in {@link CSVFormat CSVFormat JavaDoc}.
+ * </p>
+ *
  * <h4>Parsing completely into memory</h4>
  * <p>
  * You may also get a List of records: