From 389cf0047af9109d4352db59746c6f7270bea70b Mon Sep 17 00:00:00 2001
From: Peter Hull <peterhull90@gmail.com>
Date: Wed, 5 Oct 2022 20:50:04 +0100
Subject: [PATCH 1/2] Add comments to iterator() and stream()

---
 .../org/apache/commons/csv/CSVParser.java     | 21 +++++++++++++++++--
 1 file changed, 19 insertions(+), 2 deletions(-)

diff --git a/src/main/java/org/apache/commons/csv/CSVParser.java b/src/main/java/org/apache/commons/csv/CSVParser.java
index bff55a00..11d1bba7 100644
--- a/src/main/java/org/apache/commons/csv/CSVParser.java
+++ b/src/main/java/org/apache/commons/csv/CSVParser.java
@@ -734,9 +734,24 @@ public final class CSVParser implements Iterable<CSVRecord>, Closeable {
      * {@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>
+     * For example, the iterator from code such as
+     * <pre>
+     * Iterator{@code<CSVRecord>} items() throws IOException {
+     *    try (CSVParser parser = CSVParser.parse( ... )) {
+     *       return parser.iterator();
+     *    }
+     * }
+     * </pre>
+     * will never yield any records because the parser is closed by the
+     * try-with-resources block.
+     * An alternative is to extract all records as a list with
+     * {@link getRecords()}, and return an iterator to that list.
      */
     @Override
     public Iterator<CSVRecord> iterator() {
@@ -799,7 +814,9 @@ public final class CSVParser implements Iterable<CSVRecord>, Closeable {
 
     /**
      * 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()}.
      * @return a sequential {@code Stream} with this collection as its source.
      * @since 1.9.0
      */

From 5fbd3538566a0629f3d02dd8458d9b54a6013975 Mon Sep 17 00:00:00 2001
From: Peter Hull <peterhull90@gmail.com>
Date: Thu, 6 Oct 2022 13:09:02 +0100
Subject: [PATCH 2/2] Update text as requested in review

---
 .../java/org/apache/commons/csv/CSVParser.java    | 15 ++++-----------
 1 file changed, 4 insertions(+), 11 deletions(-)

diff --git a/src/main/java/org/apache/commons/csv/CSVParser.java b/src/main/java/org/apache/commons/csv/CSVParser.java
index 11d1bba7..fd4c3a90 100644
--- a/src/main/java/org/apache/commons/csv/CSVParser.java
+++ b/src/main/java/org/apache/commons/csv/CSVParser.java
@@ -740,18 +740,10 @@ public final class CSVParser implements Iterable<CSVRecord>, Closeable {
      * {@link NoSuchElementException}.
      * </p>
      * <p>
-     * For example, the iterator from code such as
-     * <pre>
-     * Iterator{@code<CSVRecord>} items() throws IOException {
-     *    try (CSVParser parser = CSVParser.parse( ... )) {
-     *       return parser.iterator();
-     *    }
-     * }
-     * </pre>
-     * will never yield any records because the parser is closed by the
-     * try-with-resources block.
-     * An alternative is to extract all records as a list with
+     * 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() {
@@ -817,6 +809,7 @@ public final class CSVParser implements Iterable<CSVRecord>, Closeable {
      * <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
      */