bufio: document ReadFrom/WriteTo calls to underlying methods

In general use of these magic methods must be documented so that
users understand what will happen.

Fixes #23289

Change-Id: Ic46915eee1d3b7e57d8d1886834ddfb2e8e66e62
Reviewed-on: https://go-review.googlesource.com/103238
Reviewed-by: Rob Pike <r@golang.org>

diff --git a/src/bufio/bufio.go b/src/bufio/bufio.go
index ad9c9f5ddf79692b38bc445fbe75c8b4ee996ec0..72545a7509541b1f5aeb9b3c13bb9e2bc7acedc7 100644 (file)
--- a/src/bufio/bufio.go
+++ b/src/bufio/bufio.go
@@ -462,6 +462,8 @@ func (b *Reader) ReadString(delim byte) (string, error) {
 
 // WriteTo implements io.WriterTo.
 // This may make multiple calls to the Read method of the underlying Reader.
+// If the underlying reader supports the WriteTo method,
+// this calls the underlying WriteTo without buffering.
 func (b *Reader) WriteTo(w io.Writer) (n int64, err error) {
        n, err = b.writeBuf(w)
        if err != nil {
@@ -684,7 +686,9 @@ func (b *Writer) WriteString(s string) (int, error) {
        return nn, nil
 }
 
-// ReadFrom implements io.ReaderFrom.
+// ReadFrom implements io.ReaderFrom. If the underlying writer
+// supports the ReadFrom method, and b has no buffered data yet,
+// this calls the underlying ReadFrom without buffering.
 func (b *Writer) ReadFrom(r io.Reader) (n int64, err error) {
        if b.Buffered() == 0 {
                if w, ok := b.wr.(io.ReaderFrom); ok {