io: clarify the behavior of PipeWriter.CloseWithError(nil).

The previous wording implied that reads would return no error, rather
than EOF. It's convenient for users to know that Close() is equivalent
to CloseWithError(nil) because it can remove a branch from their error
handling code where they want to close the pipe in the appropriate way.
For example:

    https://github.com/jacobsa/gcloud/blob/6e9a8cec0a3f0834da3e9c9725dfe0bf79cccebb/gcs/bucket.go#L637-L643

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

diff --git a/src/io/pipe.go b/src/io/pipe.go
index f65354a7f253b65a4c1718b3dae1908c55229efe..179515e78d3a03866bfcaaf7800bf670b48a14e1 100644 (file)
--- a/src/io/pipe.go
+++ b/src/io/pipe.go
@@ -168,7 +168,10 @@ func (w *PipeWriter) Close() error {
 }
 
 // CloseWithError closes the writer; subsequent reads from the
-// read half of the pipe will return no bytes and the error err.
+// read half of the pipe will return no bytes and the error err,
+// or EOF if err is nil.
+//
+// CloseWithError always returns nil.
 func (w *PipeWriter) CloseWithError(err error) error {
        w.p.wclose(err)
        return nil