code review 6760045: io: add ByteWriter interface

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 199 matching lines @@
 // UnreadByte causes the next call to ReadByte to return the same byte
 // as the previous call to ReadByte.
 // It may be an error to call UnreadByte twice without an intervening
 // call to ReadByte.
 type ByteScanner interface {
         ByteReader
         UnreadByte() error
 }
 
 // ByteWriter is the interface that wraps the WriteByte method.
-//
-// WriteByte efficiently writes a single byte, relative to the
-// equivalent Write call. Implementation of ByteWriter generally
-// are buffered in-memory.

[r, 2012/10/29 21:14:15]

two weasel-word adverbs in two sentences.
the interface cannot guarantee that it is efficient, so the documentation for
the interface should just say what it does.
by the same token, the interface cannot guarantee how the implementations work.

what are you trying to achieve in this comment? what's wrong with plain,

ByteWriter is the interface that wraps the WriteByte method.

-rob

 type ByteWriter interface {
         WriteByte(c byte) error
 }
 
 // RuneReader is the interface that wraps the ReadRune method.
 //
 // ReadRune reads a single UTF-8 encoded Unicode character
 // and returns the rune and its size in bytes. If no character is
 // available, err will be set.
 type RuneReader interface {
@@ skipping 261 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
 }