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

Comments

Projects
None yet
6 participants
@turnage
Copy link

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

This comment has been minimized.

Copy link
Contributor

commented Jun 8, 2016

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

@ianlancetaylor ianlancetaylor added this to the Go1.7Maybe milestone Jun 8, 2016

@mikioh

This comment has been minimized.

Copy link
Contributor

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 label Oct 7, 2016

@gopherbot

This comment has been minimized.

Copy link

commented Oct 27, 2016

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

@gopherbot gopherbot closed this in c01c1d4 Oct 27, 2016

@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.
You can’t perform that action at this time.