net: consistently document deadline handling

After CL 228645 some mentions of the Deadline methods referred
to the Timeout method, and some to os.ErrDeadlineExceeded.
Stop referring to the Timeout method, to encourage ErrDeadlineExceeded.

For #31449

Change-Id: I27b8ff34f31798f38b06437546886af8cce98ca4
Reviewed-on: https://go-review.googlesource.com/c/go/+/239705
Run-TryBot: Ian Lance Taylor <iant@golang.org>
Reviewed-by: Damien Neil <dneil@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>

src/net/net.go

@@ -111,13 +111,13 @@ 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 an Error with Timeout() == true
-	// after a fixed time limit; see SetDeadline and SetReadDeadline.
+	// Read can be made to time out and return an error 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 an Error with Timeout() == true
-	// after a fixed time limit; see SetDeadline and SetWriteDeadline.
+	// Write can be made to time out and return an error after a fixed
+	// time limit; see SetDeadline and SetWriteDeadline.
 	Write(b []byte) (n int, err error)
 
 	// Close closes the connection.
@@ -313,15 +313,13 @@ type PacketConn interface {
 	// It returns the number of bytes read (0 <= n <= len(p))
 	// and any error encountered. Callers should always process
 	// the n > 0 bytes returned before considering the error err.
-	// ReadFrom can be made to time out and return
-	// an Error with Timeout() == true after a fixed time limit;
-	// see SetDeadline and SetReadDeadline.
+	// ReadFrom can be made to time out and return an error after a
+	// fixed time limit; see SetDeadline and SetReadDeadline.
 	ReadFrom(p []byte) (n int, addr Addr, err error)
 
 	// WriteTo writes a packet with payload p to addr.
-	// WriteTo can be made to time out and return
-	// an Error with Timeout() == true after a fixed time limit;
-	// see SetDeadline and SetWriteDeadline.
+	// WriteTo can be made to time out and return an Error after a
+	// fixed time limit; see SetDeadline and SetWriteDeadline.
 	// On packet-oriented connections, write timeouts are rare.
 	WriteTo(p []byte, addr Addr) (n int, err error)
 
@@ -337,11 +335,17 @@ type PacketConn interface {
 	// 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.
+	// fail instead of blocking. The deadline applies to all future
+	// and pending I/O, not just the immediately following call to
+	// Read or Write. After a deadline has been exceeded, the
+	// connection can be refreshed by setting a deadline in the future.
+	//
+	// If the deadline is exceeded a call to Read or Write or to other
+	// I/O methods will return an error that wraps os.ErrDeadlineExceeded.
+	// This can be tested using errors.Is(err, os.ErrDeadlineExceeded).
+	// The error's Timeout method will return true, but note that there
+	// are other possible errors for which the Timeout method will
+	// return true even if the deadline has not been exceeded.
 	//
 	// An idle timeout can be implemented by repeatedly extending
 	// the deadline after successful ReadFrom or WriteTo calls.