net: update documentation on Resolve{TCP,UDP,IP,Unix}Addr

This change clarifies the documentation on
Resolve{TCP,UDP,IP,Unix}Addr to avoid unnecessary confusion about how
the arguments are used to make end point addresses.

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

Updates #17613.

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

4 files changed, 66 insertions, 44 deletions

diff --git a/src/net/iprawsock.go b/src/net/iprawsock.go
index c574814fa9..2ff2f508d4 100644
--- a/src/net/iprawsock.go
+++ b/src/net/iprawsock.go
@@ -61,26 +61,33 @@ func (a *IPAddr) opAddr() Addr {
 	return a
 }
 
-// ResolveIPAddr parses addr as an IP address of the form "host" or
-// "ipv6-host%zone" and resolves the domain name on the network net,
-// which must be "ip", "ip4" or "ip6".
+// ResolveIPAddr returns an address of IP end point.
 //
-// Resolving a hostname is not recommended because this returns at most
-// one of its IP addresses.
-func ResolveIPAddr(net, addr string) (*IPAddr, error) {
-	if net == "" { // a hint wildcard for Go 1.0 undocumented behavior
-		net = "ip"
+// The network must be an IP network name.
+//
+// If the host in the address parameter is not a literal IP address,
+// ResolveIPAddr resolves the address to an address of IP end point.
+// Otherwise, it parses the address as a literal IP address.
+// The address parameter can use a host name, but this is not
+// recommended, because it will return at most one of the host name's
+// IP addresses.
+//
+// See func Dial for a description of the network and address
+// parameters.
+func ResolveIPAddr(network, address string) (*IPAddr, error) {
+	if network == "" { // a hint wildcard for Go 1.0 undocumented behavior
+		network = "ip"
 	}
-	afnet, _, err := parseNetwork(context.Background(), net, false)
+	afnet, _, err := parseNetwork(context.Background(), network, false)
 	if err != nil {
 		return nil, err
 	}
 	switch afnet {
 	case "ip", "ip4", "ip6":
 	default:
-		return nil, UnknownNetworkError(net)
+		return nil, UnknownNetworkError(network)
 	}
-	addrs, err := DefaultResolver.internetAddrList(context.Background(), afnet, addr)
+	addrs, err := DefaultResolver.internetAddrList(context.Background(), afnet, address)
 	if err != nil {
 		return nil, err
 	}
diff --git a/src/net/tcpsock.go b/src/net/tcpsock.go
index 80d0f390de..74878fc614 100644
--- a/src/net/tcpsock.go
+++ b/src/net/tcpsock.go
@@ -50,24 +50,30 @@ func (a *TCPAddr) opAddr() Addr {
 	return a
 }
 
-// ResolveTCPAddr parses addr as a TCP address of the form "host:port"
-// or "[ipv6-host%zone]:port" and resolves a pair of domain name and
-// port name on the network net, which must be "tcp", "tcp4" or
-// "tcp6".  A literal address or host name for IPv6 must be enclosed
-// in square brackets, as in "[::1]:80", "[ipv6-host]:http" or
-// "[ipv6-host%zone]:80".
+// ResolveTCPAddr returns an address of TCP end point.
 //
-// Resolving a hostname is not recommended because this returns at most
-// one of its IP addresses.
-func ResolveTCPAddr(net, addr string) (*TCPAddr, error) {
-	switch net {
+// The network must be a TCP network name.
+//
+// If the host in the address parameter is not a literal IP address or
+// the port is not a literal port number, ResolveTCPAddr resolves the
+// address to an address of TCP end point.
+// Otherwise, it parses the address as a pair of literal IP address
+// and port number.
+// The address parameter can use a host name, but this is not
+// recommended, because it will return at most one of the host name's
+// IP addresses.
+//
+// See func Dial for a description of the network and address
+// parameters.
+func ResolveTCPAddr(network, address string) (*TCPAddr, error) {
+	switch network {
 	case "tcp", "tcp4", "tcp6":
 	case "": // a hint wildcard for Go 1.0 undocumented behavior
-		net = "tcp"
+		network = "tcp"
 	default:
-		return nil, UnknownNetworkError(net)
+		return nil, UnknownNetworkError(network)
 	}
-	addrs, err := DefaultResolver.internetAddrList(context.Background(), net, addr)
+	addrs, err := DefaultResolver.internetAddrList(context.Background(), network, address)
 	if err != nil {
 		return nil, err
 	}
diff --git a/src/net/udpsock.go b/src/net/udpsock.go
index 073bce83a1..219d6294cc 100644
--- a/src/net/udpsock.go
+++ b/src/net/udpsock.go
@@ -53,24 +53,30 @@ func (a *UDPAddr) opAddr() Addr {
 	return a
 }
 
-// ResolveUDPAddr parses addr as a UDP address of the form "host:port"
-// or "[ipv6-host%zone]:port" and resolves a pair of domain name and
-// port name on the network net, which must be "udp", "udp4" or
-// "udp6".  A literal address or host name for IPv6 must be enclosed
-// in square brackets, as in "[::1]:80", "[ipv6-host]:http" or
-// "[ipv6-host%zone]:80".
+// ResolveUDPAddr returns an address of UDP end point.
 //
-// Resolving a hostname is not recommended because this returns at most
-// one of its IP addresses.
-func ResolveUDPAddr(net, addr string) (*UDPAddr, error) {
-	switch net {
+// The network must be a UDP network name.
+//
+// If the host in the address parameter is not a literal IP address or
+// the port is not a literal port number, ResolveUDPAddr resolves the
+// address to an address of UDP end point.
+// Otherwise, it parses the address as a pair of literal IP address
+// and port number.
+// The address parameter can use a host name, but this is not
+// recommended, because it will return at most one of the host name's
+// IP addresses.
+//
+// See func Dial for a description of the network and address
+// parameters.
+func ResolveUDPAddr(network, address string) (*UDPAddr, error) {
+	switch network {
 	case "udp", "udp4", "udp6":
 	case "": // a hint wildcard for Go 1.0 undocumented behavior
-		net = "udp"
+		network = "udp"
 	default:
-		return nil, UnknownNetworkError(net)
+		return nil, UnknownNetworkError(network)
 	}
-	addrs, err := DefaultResolver.internetAddrList(context.Background(), net, addr)
+	addrs, err := DefaultResolver.internetAddrList(context.Background(), network, address)
 	if err != nil {
 		return nil, err
 	}
diff --git a/src/net/unixsock.go b/src/net/unixsock.go
index 18c793445f..50449fde44 100644
--- a/src/net/unixsock.go
+++ b/src/net/unixsock.go
@@ -42,15 +42,18 @@ func (a *UnixAddr) opAddr() Addr {
 	return a
 }
 
-// ResolveUnixAddr parses addr as a Unix domain socket address.
-// The string net gives the network name, "unix", "unixgram" or
-// "unixpacket".
-func ResolveUnixAddr(net, addr string) (*UnixAddr, error) {
-	switch net {
+// ResolveUnixAddr returns an address of Unix domain socket end point.
+//
+// The network must be a Unix network name.
+//
+// See func Dial for a description of the network and address
+// parameters.
+func ResolveUnixAddr(network, address string) (*UnixAddr, error) {
+	switch network {
 	case "unix", "unixgram", "unixpacket":
-		return &UnixAddr{Name: addr, Net: net}, nil
+		return &UnixAddr{Name: address, Net: network}, nil
 	default:
-		return nil, UnknownNetworkError(net)
+		return nil, UnknownNetworkError(network)
 	}
 }