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] 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
      */