From: Ian Lance Taylor <iant@golang.org>
Date: Wed, 13 Jun 2018 19:44:50 +0000 (-0700)
Subject: bufio: clarify SplitFunc docs for nil token
X-Git-Tag: go1.11beta1~109
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=1e721cfc43c4f3c4e24a386c7e283d9fec59e2f4;p=gostls13.git

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>
---

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,