encoding/csv: document that Writer is buffered

Add documentation that individual Write calls are buffered and
copy documentation from bufio.Writer notifying the user to call
Flush and Error when all writes are complete. Remove reference
to "file" since the implementation is general and allows any
io.Writer.

Fixes #30045

Change-Id: I50165470e548f296494e764707fbabe36c665015
Reviewed-on: https://go-review.googlesource.com/c/160680
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

diff --git a/src/encoding/csv/writer.go b/src/encoding/csv/writer.go
index 31c4f9c22dcfe6ffd9abd41e7d72bf7e3a8040d8..b18996a930d307eb3c7f6bbdce0faadfa7a532df 100644 (file)
--- a/src/encoding/csv/writer.go
+++ b/src/encoding/csv/writer.go
@@ -12,7 +12,7 @@ import (
        "unicode/utf8"
 )
 
-// A Writer writes records to a CSV encoded file.
+// A Writer writes records using CSV encoding.
 //
 // As returned by NewWriter, a Writer writes records terminated by a
 // newline and uses ',' as the field delimiter. The exported fields can be
@@ -21,6 +21,12 @@ import (
 // Comma is the field delimiter.
 //
 // If UseCRLF is true, the Writer ends each output line with \r\n instead of \n.
+//
+// The writes of individual records are buffered.
+// After all data has been written, the client should call the
+// Flush method to guarantee all data has been forwarded to
+// the underlying io.Writer.  Any errors that occurred should
+// be checked by calling the Error method.
 type Writer struct {
        Comma   rune // Field delimiter (set to ',' by NewWriter)
        UseCRLF bool // True to use \r\n as the line terminator
@@ -37,6 +43,8 @@ func NewWriter(w io.Writer) *Writer {
 
 // Writer writes a single CSV record to w along with any necessary quoting.
 // A record is a slice of strings with each string being one field.
+// Writes are buffered, so Flush must eventually be called to ensure
+// that the record is written to the underlying io.Writer.
 func (w *Writer) Write(record []string) error {
        if !validDelim(w.Comma) {
                return errInvalidDelim
@@ -122,7 +130,8 @@ func (w *Writer) Error() error {
        return err
 }
 
-// WriteAll writes multiple CSV records to w using Write and then calls Flush.
+// WriteAll writes multiple CSV records to w using Write and then calls Flush,
+// returning any error from the Flush.
 func (w *Writer) WriteAll(records [][]string) error {
        for _, record := range records {
                err := w.Write(record)