net: update documentation on Dial and its variants

This change clarifies the documentation on Dial and its variants to
avoid unnecessary confusion about how the arguments for the connection
setup functions are used to make connections.

Also replaces "name" or "hostname" with "host name" when the term
implies the use of DNS.

Updates #17613.
Fixes #17614.
Fixes #17738.
Fixes #17956.
Updates #18806.

Change-Id: I6adb3f2ae04a3bf83b96016ed73d8e59926f3e8a
Reviewed-on: https://go-review.googlesource.com/34875
Reviewed-by: Ian Lance Taylor <iant@golang.org>

2 files changed, 50 insertions, 26 deletions

diff --git a/src/net/dial.go b/src/net/dial.go
index 631ca44165..926fc26670 100644
--- a/src/net/dial.go
+++ b/src/net/dial.go
@@ -23,8 +23,8 @@ type Dialer struct {
 	//
 	// The default is no timeout.
 	//
-	// When dialing a name with multiple IP addresses, the timeout
-	// may be divided between them.
+	// When using TCP and dialing a host name with multiple IP
+	// addresses, the timeout may be divided between them.
 	//
 	// With or without a timeout, the operating system may impose
 	// its own earlier timeout. For instance, TCP timeouts are
@@ -43,10 +43,11 @@ type Dialer struct {
 	// If nil, a local address is automatically chosen.
 	LocalAddr Addr
 
-	// DualStack enables RFC 6555-compliant "Happy Eyeballs" dialing
-	// when the network is "tcp" and the destination is a host name
-	// with both IPv4 and IPv6 addresses. This allows a client to
-	// tolerate networks where one address family is silently broken.
+	// DualStack enables RFC 6555-compliant "Happy Eyeballs"
+	// dialing when the network is "tcp" and the host in the
+	// address parameter resolves to both IPv4 and IPv6 addresses.
+	// This allows a client to tolerate networks where one address
+	// family is silently broken.
 	DualStack bool
 
 	// FallbackDelay specifies the length of time to wait before
@@ -246,39 +247,60 @@ func (r *Resolver) resolveAddrList(ctx context.Context, op, network, addr string
 // (IPv4-only), "ip6" (IPv6-only), "unix", "unixgram" and
 // "unixpacket".
 //
-// For TCP and UDP networks, addresses have the form host:port.
-// If host is a literal IPv6 address it must be enclosed
-// in square brackets as in "[::1]:80" or "[ipv6-host%zone]:80".
-// The functions JoinHostPort and SplitHostPort manipulate addresses
-// in this form.
-// If the host is empty, as in ":80", the local system is assumed.
+// For TCP and UDP networks, the address has the form "host:port".
+// The host must be a literal IP address, or a host name that can be
+// resolved to IP addresses.
+// The port must be a literal port number or a service name.
+// If the host is a literal IPv6 address it must be enclosed in square
+// brackets, as in "[2001:db8::1]:80" or "[fe80::1%zone]:80".
+// The zone specifies the scope of the literal IPv6 address as defined
+// in RFC 4007.
+// The functions JoinHostPort and SplitHostPort manipulate a pair of
+// host and port in this form.
+// When using TCP, and the host resolves to multiple IP addresses,
+// Dial will try each IP address in order until one succeeds.
 //
 // Examples:
-//	Dial("tcp", "192.0.2.1:80")
 //	Dial("tcp", "golang.org:http")
-//	Dial("tcp", "[2001:db8::1]:http")
-//	Dial("tcp", "[fe80::1%lo0]:80")
+//	Dial("tcp", "192.0.2.1:http")
+//	Dial("tcp", "198.51.100.1:80")
+//	Dial("udp", "[2001:db8::1]:domain")
+//	Dial("udp", "[fe80::1%lo0]:53")
 //	Dial("tcp", ":80")
 //
 // For IP networks, the network must be "ip", "ip4" or "ip6" followed
-// by a colon and a protocol number or name and the addr must be a
-// literal IP address.
+// by a colon and a literal protocol number or a protocol name, and
+// the address has the form "host". The host must be a literal IP
+// address or a literal IPv6 address with zone.
+// It depends on each operating system how the operating system
+// behaves with a non-well known protocol number such as "0" or "255".
 //
 // Examples:
 //	Dial("ip4:1", "192.0.2.1")
 //	Dial("ip6:ipv6-icmp", "2001:db8::1")
+//	Dial("ip6:58", "fe80::1%lo0")
 //
-// For Unix networks, the address must be a file system path.
+// For TCP, UDP and IP networks, if the host is empty or a literal
+// unspecified IP address, as in ":80", "0.0.0.0:80" or "[::]:80" for
+// TCP and UDP, "", "0.0.0.0" or "::" for IP, the local system is
+// assumed.
 //
-// If the host is resolved to multiple addresses,
-// Dial will try each address in order until one succeeds.
+// For Unix networks, the address must be a file system path.
 func Dial(network, address string) (Conn, error) {
 	var d Dialer
 	return d.Dial(network, address)
 }
 
 // DialTimeout acts like Dial but takes a timeout.
+//
 // The timeout includes name resolution, if required.
+// When using TCP, and the host in the address parameter resolves to
+// multiple IP addresses, the timeout is spread over each consecutive
+// dial, such that each is given an appropriate fraction of the time
+// to connect.
+//
+// See func Dial for a description of the network and address
+// parameters.
 func DialTimeout(network, address string, timeout time.Duration) (Conn, error) {
 	d := Dialer{Timeout: timeout}
 	return d.Dial(network, address)
diff --git a/src/net/lookup.go b/src/net/lookup.go
index 4490784236..c05731ffb3 100644
--- a/src/net/lookup.go
+++ b/src/net/lookup.go
@@ -109,14 +109,16 @@ type Resolver struct {
 
 	// Dial optionally specifies an alternate dialer for use by
 	// Go's built-in DNS resolver to make TCP and UDP connections
-	// to DNS services. The provided addr will always be an IP
-	// address and not a hostname.
+	// to DNS services. The host in the address parameter will
+	// always be a literal IP address and not a host name, and the
+	// port in the address parameter will be a literal port number
+	// and not a service name.
 	// If the Conn returned is also a PacketConn, sent and received DNS
-	// messages must adhere to section 4.2.1. "UDP usage" of RFC 1035.
-	// Otherwise, DNS messages transmitted over Conn must adhere to section
-	// 4.2.2. "TCP usage".
+	// messages must adhere to RFC 1035 section 4.2.1, "UDP usage".
+	// Otherwise, DNS messages transmitted over Conn must adhere
+	// to RFC 7766 section 5, "Transport Protocol Selection".
 	// If nil, the default dialer is used.
-	Dial func(ctx context.Context, network, addr string) (Conn, error)
+	Dial func(ctx context.Context, network, address string) (Conn, error)
 
 	// TODO(bradfitz): optional interface impl override hook
 	// TODO(bradfitz): Timeout time.Duration?