net: incomplete documentation on parameters for Dial, Listen and ListenPacket functions

[mikioh]

The current package documentation describes like the following:

func Dial(network, address string) (Conn, error)
    Dial connects to the address on the named network.

   (snip)

    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.

It doesn't describe that the second parameter could be not only an IP address literal but a DNS/mDNS name or a name in local database. Also the parameter name address looks a bit confusing; host or other appropriate word would be better for avoiding unnecessary confusion.

[quentinmit]

I think the docs are already pretty clear that the parameter takes a host name (of any form), but CLs are always welcome to improve docs.

[as]

@mikioh

Host is not the appropriate word because the string represents a host and port pair, referred to as a socket (RFC 793).

On the other hand, address makes sense to me and changing it seems unnecessary.

[bradfitz]

Agreed. Let's stick with addr or address as we already do ~everywhere in Go's docs. Feel free to send docs making it clear that hostnames are okay too.

[mikioh]

I don't think Dial or Listen treats only TCP (RFC 793) connection endpoints. For raw IP connection endpoints the argument for 2nd parameter must be a name or IP literal, and for Unix-domain connection endpoints the argument must be a filesystem path.

If there is no appropriate word like authority in https://tools.ietf.org/html/rfc3986#section-3.2 and sticking with address, please document with a distinction between address and IP address.

[as]

@mikioh

Address is just a string, but the common case is host:port. Would it suffice to add examples of other address types than change the terminology at this point?

[mikioh]

@as,

Probably, not sure. FWIW, when I saw the description of https://go-review.googlesource.com/27250 I couldn't parse it; what are the .local addresses? Is that a sequence of labels end with ".local", non-global routable addresses or a list of addresses mapped to a sequence of labels end with ".local"? I hope that the updated documentation will avoid such unnecessary confusion.

[mikioh]

How about local and remote or localID and remoteID? For example,

// Dial connects to remote on the named network.
//
// Known networks are "tcp", "tcp4" (IPv4-only), "tcp6" (IPv6-only),
// "udp", "udp4" (IPv4-only), "udp6" (IPv6-only), "ip", "ip4"
// (IPv4-only), "ip6" (IPv6-only), "unix", "unixgram" and
// "unixpacket".
//
// For TCP and UDP networks, the provided remote has the form
// "host:port":
//   - If the host is a name, it must be a resolvable name using DNS
//     or other resolution services provided by the local system.
//   - If the host is an IPv4 address literal, the address must be in
//     dotted-decial nonation.
//   - If the host is an IPv6 address literal as defined in RFC 5952,
//     the address must be enclosed in square brackets as in
//     "[::1]:80" or "[::1%lo0]:80".
//     The functions JoinHostPort and SplitHostPort manipulate hosts
//     in this form.
//   - If the host is empty, as in ":80", the local system is assumed.
//   - If the port is a name, it must be a resolvable service name
//     using DNS or other resolution services provided by the local
//     system.
//   - If the port is a number literal, it must be a deciaml integer
//     from "0" to "65535".
//
// 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", ":80")
//
// For IP networks, the network must be "ip", "ip4" or "ip6" followed
// by a colon and a protocol number or name and the provided remote
// must be an IP address literal.
//
// Examples:
//      Dial("ip4:1", "192.0.2.1")
//      Dial("ip6:ipv6-icmp", "2001:db8::1")
//
// For Unix networks, the provided remote must be a file system path.
func Dial(network, remote string) (Conn, error)

[gopherbot]

CL https://golang.org/cl/34875 mentions this issue.

[gopherbot]

CL https://golang.org/cl/34876 mentions this issue.