encoding/csv: document Read error behavior

Fixes #17342.

Change-Id: I76af756d7aff464554c5564d444962a468d0eccc
Reviewed-on: https://go-review.googlesource.com/32172
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Quentin Smith <quentin@golang.org>

diff --git a/src/encoding/csv/reader.go b/src/encoding/csv/reader.go
index 28caa6aa2728a807c6a7883387094865c8f31fb2..c8c4ca775832dfe750e512b720ac6e44c122fe5e 100644 (file)
--- a/src/encoding/csv/reader.go
+++ b/src/encoding/csv/reader.go
@@ -141,8 +141,12 @@ func (r *Reader) error(err error) error {
        }
 }
 
-// Read reads one record from r. The record is a slice of strings with each
-// string representing one field.
+// Read reads one record (a slice of fields) from r.
+// If the record has an unexpected number of fields,
+// Read returns the record along with the error ErrFieldCount.
+// Except for that case, Read always returns either a non-nil
+// record or a non-nil error, but not both.
+// If there is no data left to be read, Read returns nil, io.EOF.
 func (r *Reader) Read() (record []string, err error) {
        for {
                record, err = r.parseRecord()