code review 87780046: io: document that a Writer must not write to p

src/pkg/io/io.go

 // Copyright 2009 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 // Package io provides basic interfaces to I/O primitives.
 // Its primary job is to wrap existing implementations of such primitives,
 // such as those in package os, into shared public interfaces that
 // abstract the functionality, plus some other related primitives.
 //
 // Because these interfaces and primitives wrap lower-level operations with
@@ skipping 56 matching lines @@
 type Reader interface {
         Read(p []byte) (n int, err error)
 }
 
 // Writer is the interface that wraps the basic Write method.
 //
 // Write writes len(p) bytes from p to the underlying data stream.
 // It returns the number of bytes written from p (0 <= n <= len(p))
 // and any error encountered that caused the write to stop early.
 // Write must return a non-nil error if it returns n < len(p).
-// Write must not write to the slice p.

[r, 2014/04/15 22:49:58]

I'm sorry but "Write must not write..." is odd and confusing phrasing. Plus it
can modify p (the variable), just not the contents. That's why I made my
suggestion, which I still prefer: "Write must not modify the contents of p."

Also, it's the implementation we're talking about, not the interface, and you
called it "it" already,so how about:

It must return a non-nil error if it returns n < len(p).
Also, it must not modify the contents of p.

[bradfitz, 2014/04/15 22:55:56]

I still object.

There's a difference between leaving the buffer how you found it when you return
from Write vs data races in the presence of many goroutines reading from the
same buffer.

In fact, the very next question on the mailing list was _just that_.

We need to be clear here that assigning/writing (pick a word) to the contents of
the p is not allowed.

[r, 2014/04/15 22:57:34]

Sigh. Well, at least if we use 'it' we don't have "Write must not write".

It must not write to the contents of the slice p.

+// Write must not modify the slice data, even temporarily.
 type Writer interface {
         Write(p []byte) (n int, err error)
 }
 
 // Closer is the interface that wraps the basic Close method.
 //
 // The behavior of Close after the first call is undefined.
 // Specific implementations may document their own behavior.
 type Closer interface {
         Close() error
@@ skipping 396 matching lines @@
 
 func (t *teeReader) Read(p []byte) (n int, err error) {
         n, err = t.r.Read(p)
         if n > 0 {
                 if n, err := t.w.Write(p[:n]); err != nil {
                         return n, err
                 }
         }
         return
 }