net: Addr interface documentation unclear

[turnage]

The Addr Network() method's comment/doc is unclear.

The Network() method as implemented by IPAddr is not the name of a given network, but the name of the protocol of the Addr implementation.

Maybe "Network Name" is the appropriate terminology for this, but it is hard to search. I don't know what it should say but I think more would be helpful.

Edits: ianlancetaylor's correction.

[ianlancetaylor]

The net.Addr interface does not have a Name method. I assume you mean the Network method.

[mikioh]

FWIW, I have a draft for #10624 like the following, but it's still too much explanation. Need a wordsmith.

Networks, Hosts and Services

The network, host and service parameters specify the detail of communicaton
facilities for Dial, Listen, Lookup and Resolve functions.

The networks:

The known networks are "tcp", "tcp4", "tcp6", "udp", "udp4", "udp6", "ip",
"ip4", ip6", "unix", "unixgram" and "unixpacket".
A name ending with "4" uses only IPv4 and "6" uses only IPv6 as a network layer
protocol.

        "tcp"           TCP over either IPv4 or IPv6 communication
                        the network protocol will be chosen automatically
        "tcp4"          TCP over IPv4 communication
        "tcp6"          TCP over IPv6 communication
        "udp"           UDP over either IPv4 or IPv6 communication
                        the network protocol will be chosen automatically
        "udp4"          UDP over IPv4 communication
        "udp6"          UDP over IPv6 communication
        "ip"            either raw IPv4 or IPv6 communication
                        the network protocol will be chosen automatically
        "ip4"           raw IPv4 communication
        "ip6"           raw IPv6 communication
        "unix"          host-local connection-oriented stream communication
        "unixgram"      host-local datagram communication
        "unixpacket"    host-local connection-oriented datagram communication

The raw IP network must be "ip", "ip4" or "ip6" followed by a colon and a
protocol number or name, e.g. "ip4:1", "ip6:58", "ip:icmp", "ip:ipv6-icmp".

The hosts:

        IPv4 literal    dotted decimal form, e.g. "192.0.2.1"
        IPv6 literal    colon-separated hexadecimal form, with IPv6 zone
                        identifier separated by a percent sign if required,
                        e.g. "2001:db8::1", "fe80::1%eth0"
        name on IP network
                        opaque string, which is mostly a host name or domain
                        name, e.g. "golang.org"
        name on Unix network
                        opaque string, which is mostly a file system path

The services:

        number literal on IP network
                        decimal digits, e.g. "80"
        name on IP network
                        opaque string, which is mostly a service name,
                        e.g. "http"

The hosts with services:

        IPv4 literal    colon-separated host and service,
                        e.g. "192.0.2.1:80", "192.0.2.1:http"
        IPv6 literal    colon-separated host enclosed in square brackets and
                        service, e.g. "[2001:db8::1]:80", "[2001:db8::1]:http",
                        "[fe80::1%eth0]:80"
        name on IP network
                        colon-separated host and service,
                        e.g. "golang.org:80", "golang.org:http"

TODO:
- describe the detail of IP address and service wildcard stuff

[gopherbot]

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