bufio: clarify SplitFunc docs for nil token

Fixes #25472

Change-Id: Idb72ed06a3dc43c49ab984a80f8885352b036465
Reviewed-on: https://go-review.googlesource.com/118695
Reviewed-by: Rob Pike <r@golang.org>

1 files changed, 12 insertions, 7 deletions

diff --git a/src/bufio/scan.go b/src/bufio/scan.go
index 40aaa4ab81..cefd261464 100644
--- a/src/bufio/scan.go
+++ b/src/bufio/scan.go
@@ -45,14 +45,19 @@ type Scanner struct {
 // input. The arguments are an initial substring of the remaining unprocessed
 // data and a flag, atEOF, that reports whether the Reader has no more data
 // to give. The return values are the number of bytes to advance the input
-// and the next token to return to the user, plus an error, if any. If the
-// data does not yet hold a complete token, for instance if it has no newline
-// while scanning lines, SplitFunc can return (0, nil, nil) to signal the
-// Scanner to read more data into the slice and try again with a longer slice
-// starting at the same point in the input.
+// and the next token to return to the user, if any, plus an error, if any.
 //
-// If the returned error is non-nil, scanning stops and the error
-// is returned to the client.
+// Scanning stops if the function returns an error, in which case some of
+// the input may be discarded.
+//
+// Otherwise, the Scanner advances the input. If the token is not nil,
+// the Scanner returns it to the user. If the token is nil, the
+// Scanner reads more data and continues scanning; if there is no more
+// data--if atEOF was true--the Scanner returns. If the data does not
+// yet hold a complete token, for instance if it has no newline while
+// scanning lines, a SplitFunc can return (0, nil, nil) to signal the
+// Scanner to read more data into the slice and try again with a
+// longer slice starting at the same point in the input.
 //
 // The function is never called with an empty data slice unless atEOF
 // is true. If atEOF is true, however, data may be non-empty and,