io: document and test MultiWriter error behavior

MultiWriter(w1, w2) only writes to w2 if w1.Write succeeds.
I did not know this, and it was not documented.
Document and test.

Change-Id: Idec2e8444d5a7aca0b95d07814a28daa454eb1d3
Reviewed-on: https://go-review.googlesource.com/78123
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Joe Tsai <thebrokentoaster@gmail.com>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>

src/io/multi.go

@@ -95,6 +95,10 @@ func (t *multiWriter) WriteString(s string) (n int, err error) {
 
 // MultiWriter creates a writer that duplicates its writes to all the
 // provided writers, similar to the Unix tee(1) command.
+//
+// Each write is written to each listed writer, one at a time.
+// If a listed writer returns an error, that overall write operation
+// stops and returns the error; it does not continue down the list.
 func MultiWriter(writers ...Writer) Writer {
 	allWriters := make([]Writer, 0, len(writers))
 	for _, w := range writers {

src/io/multi_test.go

@@ -176,6 +176,21 @@ func TestMultiWriterSingleChainFlatten(t *testing.T) {
 	}
 }
 
+func TestMultiWriterError(t *testing.T) {
+	f1 := writerFunc(func(p []byte) (int, error) {
+		return len(p) / 2, ErrShortWrite
+	})
+	f2 := writerFunc(func(p []byte) (int, error) {
+		t.Errorf("MultiWriter called f2.Write")
+		return len(p), nil
+	})
+	w := MultiWriter(f1, f2)
+	n, err := w.Write(make([]byte, 100))
+	if n != 50 || err != ErrShortWrite {
+		t.Errorf("Write = %d, %v, want 50, ErrShortWrite", n, err)
+	}
+}
+
 // Test that MultiReader copies the input slice and is insulated from future modification.
 func TestMultiReaderCopy(t *testing.T) {
 	slice := []Reader{strings.NewReader("hello world")}