From 94693531ebacbffad98320d9bc040f00c5cbe000 Mon Sep 17 00:00:00 2001
From: Jeff Erickson <jeff@erick.so>
Date: Tue, 15 May 2018 07:15:47 -0400
Subject: [PATCH] Expand documentation for *Iter.Next

The documentation now explains the difference between calling Err and
Close after Next returns false.

The example code has been expanded to include checking for timeout.
---
 session.go | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/session.go b/session.go
index 61a9cb22d..2aa7ad409 100644
--- a/session.go
+++ b/session.go
@@ -4265,9 +4265,11 @@ func (iter *Iter) Timeout() bool {
 //
 // Next returns true if a document was successfully unmarshalled onto result,
 // and false at the end of the result set or if an error happened.
-// When Next returns false, the Err method should be called to verify if
-// there was an error during iteration, and the Timeout method to verify if the
-// false return value was caused by a timeout (no available results).
+// When Next returns false, either the Err method or the Close method should be
+// called to verify if there was an error during iteration. While both will
+// return the error (or nil), Close will also release the cursor on the server.
+// The Timeout method may also be called to verify if the false return value
+// was caused by a timeout (no available results).
 //
 // For example:
 //
@@ -4275,6 +4277,9 @@ func (iter *Iter) Timeout() bool {
 //    for iter.Next(&result) {
 //        fmt.Printf("Result: %v\n", result.Id)
 //    }
+//    if iter.Timeout() {
+//        // react to timeout
+//    }
 //    if err := iter.Close(); err != nil {
 //        return err
 //    }