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>

diff --git a/src/net/iprawsock.go b/src/net/iprawsock.go
index c574814fa9c353a775e7f554263b9ee2b4fc5c67..2ff2f508d4602231ec826d9ebc6adcea0ae27519 100644 (file)
--- 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 80d0f390de279f7735379168d9af649ee11266a8..74878fc614a6c50042fae6c6c4fc07e5c71f9b4d 100644 (file)
--- 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 073bce83a1dd938832b4dbf45fe88502ff0d3e8c..219d6294cc36e838716ce881674339cecf5f9cee 100644 (file)
--- 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 18c793445f8125d1b2cef7877aae5ecc9f4e0402..50449fde44f9bc1f8cc41ebad6b614305f741940 100644 (file)
--- 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)
        }
 }