Merge pull request apache#270 from pedro-w/csv-274-documentation

[CSV-274] Add comments to iterator() and stream()

Author: garydgregory

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

@@ -734,9 +734,16 @@ private boolean isStrictQuoteMode() {
      * {@link IllegalStateException}.
      * </p>
      * <p>
-     * If the parser is closed a call to {@link Iterator#next()} will throw a
+     * If the parser is closed, the iterator will not yield any more records.
+     * A call to {@link Iterator#hasNext()} will return {@code false} and
+     * a call to {@link Iterator#next()} will throw a
      * {@link NoSuchElementException}.
      * </p>
+     * <p>
+     * If it is necessary to construct an iterator which is usable after the
+     * parser is closed, one option is to extract all records as a list with
+     * {@link getRecords()}, and return an iterator to that list.
+     * </p>
      */
     @Override
     public Iterator<CSVRecord> iterator() {
@@ -799,7 +806,10 @@ CSVRecord nextRecord() throws IOException {
 
     /**
      * Returns a sequential {@code Stream} with this collection as its source.
-     *
+     * <p>
+     * If the parser is closed, the stream will not produce any more values.
+     * See the comments in {@link iterator()}.
+     * </p>
      * @return a sequential {@code Stream} with this collection as its source.
      * @since 1.9.0
      */