net: correct docs of KeepAlive field in Dialer type

KeepAlive field used to report the wording "keep-alive period"
which may be misleading. This field does not represent the whole
TCP keepalive time, that is the inactivity period upon which one
endpoint starts probing the other end. But it acctually specifies
the keepalive interval, that is the time between two keepalive
probes.

Fixes #29089

Change-Id: If99b38ba108830d0e5fe527171a2f5c96a3bcde7
Reviewed-on: https://go-review.googlesource.com/c/go/+/155960
Reviewed-by: Brad Fitzpatrick <[email protected]>

Author: gmichelo

src/net/dial.go

@@ -63,12 +63,13 @@ type Dialer struct {
 	// A negative value disables Fast Fallback support.
 	FallbackDelay time.Duration
 
-	// KeepAlive specifies the keep-alive period for an active
-	// network connection.
-	// If zero, keep-alives are enabled if supported by the protocol
-	// and operating system. Network protocols or operating systems
-	// that do not support keep-alives ignore this field.
-	// If negative, keep-alives are disabled.
+	// KeepAlive specifies the interval between keep-alive
+	// probes for an active network connection.
+	// If zero, keep-alive probes are sent with a default value
+	// (currently 15 seconds), if supported by the protocol and operating
+	// system. Network protocols or operating systems that do
+	// not support keep-alives ignore this field.
+	// If negative, keep-alive probes are disabled.
 	KeepAlive time.Duration
 
 	// Resolver optionally specifies an alternate resolver to use.

src/net/http/httputil/persist.go

@@ -292,8 +292,8 @@ func (cc *ClientConn) Close() error {
 }
 
 // Write writes a request. An ErrPersistEOF error is returned if the connection
-// has been closed in an HTTP keepalive sense. If req.Close equals true, the
-// keepalive connection is logically closed after this request and the opposing
+// has been closed in an HTTP keep-alive sense. If req.Close equals true, the
+// keep-alive connection is logically closed after this request and the opposing
 // server is informed. An ErrUnexpectedEOF indicates the remote closed the
 // underlying TCP connection, which is usually considered as graceful close.
 func (cc *ClientConn) Write(req *http.Request) error {

src/net/tcpsock.go

@@ -154,7 +154,7 @@ func (c *TCPConn) SetLinger(sec int) error {
 }
 
 // SetKeepAlive sets whether the operating system should send
-// keepalive messages on the connection.
+// keep-alive messages on the connection.
 func (c *TCPConn) SetKeepAlive(keepalive bool) error {
 	if !c.ok() {
 		return syscall.EINVAL
@@ -165,7 +165,7 @@ func (c *TCPConn) SetKeepAlive(keepalive bool) error {
 	return nil
 }
 
-// SetKeepAlivePeriod sets period between keep alives.
+// SetKeepAlivePeriod sets period between keep-alives.
 func (c *TCPConn) SetKeepAlivePeriod(d time.Duration) error {
 	if !c.ok() {
 		return syscall.EINVAL