Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

net: Addr interface documentation unclear #16014

Closed
turnage opened this issue Jun 8, 2016 · 3 comments
Closed

net: Addr interface documentation unclear #16014

turnage opened this issue Jun 8, 2016 · 3 comments
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@turnage
Copy link

turnage commented Jun 8, 2016

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 ianlancetaylor changed the title Addr interface documentation unclear. net: Addr interface documentation unclear Jun 8, 2016
@ianlancetaylor
Copy link
Contributor

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

@mikioh
Copy link
Contributor

mikioh commented Jun 9, 2016

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

@adg adg modified the milestones: Go1.8, Go1.7Maybe Jun 27, 2016
@quentinmit quentinmit added the NeedsFix The path to resolution is known, but the work has not been done. label Oct 7, 2016
@gopherbot
Copy link

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

@golang golang locked and limited conversation to collaborators Oct 27, 2017
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

6 participants