net: update documentation on Conn and PacketConn

Fixes #17982

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

diff --git a/src/net/net.go b/src/net/net.go
index e28ead0833130b7385dfb13b0f6fbc0679dc0323..81206ea1cb6c837cad43ab04d0f5e8f707900595 100644 (file)
--- a/src/net/net.go
+++ b/src/net/net.go
@@ -116,12 +116,12 @@ type Addr interface {
 // Multiple goroutines may invoke methods on a Conn simultaneously.
 type Conn interface {
        // Read reads data from the connection.
-       // Read can be made to time out and return a Error with Timeout() == true
+       // Read can be made to time out and return an Error with Timeout() == true
        // after a fixed time limit; see SetDeadline and SetReadDeadline.
        Read(b []byte) (n int, err error)
 
        // Write writes data to the connection.
-       // Write can be made to time out and return a Error with Timeout() == true
+       // Write can be made to time out and return an Error with Timeout() == true
        // after a fixed time limit; see SetDeadline and SetWriteDeadline.
        Write(b []byte) (n int, err error)
 
@@ -143,7 +143,8 @@ type Conn interface {
        // fail with a timeout (see type Error) instead of
        // blocking. The deadline applies to all future and pending
        // I/O, not just the immediately following call to Read or
-       // Write.
+       // Write. After a deadline has been exceeded, the connection
+       // can be refreshed by setting a deadline in the future.
        //
        // An idle timeout can be implemented by repeatedly extending
        // the deadline after successful Read or Write calls.
@@ -309,13 +310,13 @@ type PacketConn interface {
        // bytes copied into b and the return address that
        // was on the packet.
        // ReadFrom can be made to time out and return
-       // an error with Timeout() == true after a fixed time limit;
+       // an Error with Timeout() == true after a fixed time limit;
        // see SetDeadline and SetReadDeadline.
        ReadFrom(b []byte) (n int, addr Addr, err error)
 
        // WriteTo writes a packet with payload b to addr.
        // WriteTo can be made to time out and return
-       // an error with Timeout() == true after a fixed time limit;
+       // an Error with Timeout() == true after a fixed time limit;
        // see SetDeadline and SetWriteDeadline.
        // On packet-oriented connections, write timeouts are rare.
        WriteTo(b []byte, addr Addr) (n int, err error)
@@ -328,21 +329,32 @@ type PacketConn interface {
        LocalAddr() Addr
 
        // SetDeadline sets the read and write deadlines associated
-       // with the connection.
+       // with the connection. It is equivalent to calling both
+       // SetReadDeadline and SetWriteDeadline.
+       //
+       // A deadline is an absolute time after which I/O operations
+       // fail with a timeout (see type Error) instead of
+       // blocking. The deadline applies to all future and pending
+       // I/O, not just the immediately following call to ReadFrom or
+       // WriteTo. After a deadline has been exceeded, the connection
+       // can be refreshed by setting a deadline in the future.
+       //
+       // An idle timeout can be implemented by repeatedly extending
+       // the deadline after successful ReadFrom or WriteTo calls.
+       //
+       // A zero value for t means I/O operations will not time out.
        SetDeadline(t time.Time) error
 
-       // SetReadDeadline sets the deadline for future Read calls.
-       // If the deadline is reached, Read will fail with a timeout
-       // (see type Error) instead of blocking.
-       // A zero value for t means Read will not time out.
+       // SetReadDeadline sets the deadline for future ReadFrom calls
+       // and any currently-blocked ReadFrom call.
+       // A zero value for t means ReadFrom will not time out.
        SetReadDeadline(t time.Time) error
 
-       // SetWriteDeadline sets the deadline for future Write calls.
-       // If the deadline is reached, Write will fail with a timeout
-       // (see type Error) instead of blocking.
-       // A zero value for t means Write will not time out.
+       // SetWriteDeadline sets the deadline for future WriteTo calls
+       // and any currently-blocked WriteTo call.
        // Even if write times out, it may return n > 0, indicating that
        // some of the data was successfully written.
+       // A zero value for t means WriteTo will not time out.
        SetWriteDeadline(t time.Time) error
 }