From e4f72071f89b69037193e5eb2b12f4cd0847861e Mon Sep 17 00:00:00 2001
From: WGH <wgh@torlan.ru>
Date: Sat, 4 May 2024 20:02:04 +0300
Subject: [PATCH] Document that generic helpers call rows.Close()

Existing generic helpers always call defer rows.Close().
Examples of their usage also omit external defer rows.Close() call.

For clarity, state that explicitly, because that's another point
why one would want to switch to generic helpers from manually written
rows.Next() loop.
---
 doc.go  | 2 +-
 rows.go | 8 ++++++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/doc.go b/doc.go
index db99fc4c..911571b1 100644
--- a/doc.go
+++ b/doc.go
@@ -23,7 +23,7 @@ github.com/jackc/pgx/v5/pgxpool for a concurrency safe connection pool.
 Query Interface
 
 pgx implements Query in the familiar database/sql style. However, pgx provides generic functions such as CollectRows and
-ForEachRow that are a simpler and safer way of processing rows than manually calling rows.Next(), rows.Scan, and
+ForEachRow that are a simpler and safer way of processing rows than manually calling defer rows.Close(), rows.Next(), rows.Scan, and
 rows.Err().
 
 CollectRows can be used collect all returned rows into a slice.
diff --git a/rows.go b/rows.go
index 78723d6c..d4f7a901 100644
--- a/rows.go
+++ b/rows.go
@@ -419,6 +419,8 @@ type CollectableRow interface {
 type RowToFunc[T any] func(row CollectableRow) (T, error)
 
 // AppendRows iterates through rows, calling fn for each row, and appending the results into a slice of T.
+//
+// This function closes the rows automatically on return.
 func AppendRows[T any, S ~[]T](slice S, rows Rows, fn RowToFunc[T]) (S, error) {
 	defer rows.Close()
 
@@ -438,12 +440,16 @@ func AppendRows[T any, S ~[]T](slice S, rows Rows, fn RowToFunc[T]) (S, error) {
 }
 
 // CollectRows iterates through rows, calling fn for each row, and collecting the results into a slice of T.
+//
+// This function closes the rows automatically on return.
 func CollectRows[T any](rows Rows, fn RowToFunc[T]) ([]T, error) {
 	return AppendRows([]T{}, rows, fn)
 }
 
 // CollectOneRow calls fn for the first row in rows and returns the result. If no rows are found returns an error where errors.Is(ErrNoRows) is true.
 // CollectOneRow is to CollectRows as QueryRow is to Query.
+//
+// This function closes the rows automatically on return.
 func CollectOneRow[T any](rows Rows, fn RowToFunc[T]) (T, error) {
 	defer rows.Close()
 
@@ -469,6 +475,8 @@ func CollectOneRow[T any](rows Rows, fn RowToFunc[T]) (T, error) {
 // CollectExactlyOneRow calls fn for the first row in rows and returns the result.
 //   - If no rows are found returns an error where errors.Is(ErrNoRows) is true.
 //   - If more than 1 row is found returns an error where errors.Is(ErrTooManyRows) is true.
+//
+// This function closes the rows automatically on return.
 func CollectExactlyOneRow[T any](rows Rows, fn RowToFunc[T]) (T, error) {
 	defer rows.Close()