net: document that a keep-alive failure also returns a timeout

Updates #31449

Change-Id: I76490c5e83eb2f7ba529b387a57ba088428aece5
Reviewed-on: https://go-review.googlesource.com/c/go/+/189757
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Emmanuel Odeke <emm.odeke@gmail.com>
Reviewed-by: Filippo Valsorda <filippo@golang.org>

src/net/net.go

diff --git a/src/net/net.go b/src/net/net.go
index 4ed4023..38c6b99 100644
--- a/src/net/net.go
+++ b/src/net/net.go
@@ -146,6 +146,13 @@
 	// the deadline after successful Read or Write calls.
 	//
 	// A zero value for t means I/O operations will not time out.
+	//
+	// Note that if a TCP connection has keep-alive turned on,
+	// which is the default unless overridden by Dialer.KeepAlive
+	// or ListenConfig.KeepAlive, then a keep-alive failure may
+	// also return a timeout error. On Unix systems a keep-alive
+	// failure on I/O can be detected using
+	// errors.Is(err, syscall.ETIMEDOUT).
 	SetDeadline(t time.Time) error
 
 	// SetReadDeadline sets the deadline for future Read calls