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: incomplete documentation on parameters for Dial, Listen and ListenPacket functions #17956

Closed
mikioh opened this issue Nov 17, 2016 · 9 comments

Comments

Projects
None yet
5 participants
@mikioh
Copy link
Contributor

commented Nov 17, 2016

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 quentinmit added this to the Unplanned milestone Nov 17, 2016

@quentinmit quentinmit added the NeedsFix label Nov 17, 2016

@quentinmit

This comment has been minimized.

Copy link
Contributor

commented Nov 17, 2016

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

This comment has been minimized.

Copy link
Contributor

commented Nov 19, 2016

@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

This comment has been minimized.

Copy link
Member

commented Nov 19, 2016

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

This comment has been minimized.

Copy link
Contributor Author

commented Nov 19, 2016

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.

@mikioh mikioh changed the title net: incomplete documentation on parameters for Dial and Listen functions net: incomplete documentation on parameters for Dial, Listen and ListenPacket functions Nov 20, 2016

@as

This comment has been minimized.

Copy link
Contributor

commented Nov 20, 2016

@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

This comment has been minimized.

Copy link
Contributor Author

commented Nov 24, 2016

@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

This comment has been minimized.

Copy link
Contributor Author

commented Dec 1, 2016

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

This comment has been minimized.

Copy link

commented Jan 8, 2017

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

@gopherbot

This comment has been minimized.

Copy link

commented Jan 8, 2017

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

@gopherbot gopherbot closed this in 7e63ce6 Jun 22, 2017

gopherbot pushed a commit that referenced this issue Jun 22, 2017

Mikio Hara
net: update documentation on Listen and ListenPacket
This change clarifies the documentation on Listen and ListenPacket to
avoid unnecessary confusion about how the arguments for the connection
setup functions are used to make connections.

Also replaces "name" or "hostname" with "host name" when the term
implies the use of DNS.

Updates #17613.
Updates #17614.
Updates #17615.
Fixes #17616.
Updates #17738.
Updates #17956.

Change-Id: I0bad2e143207666f2358d397fc076548ee6c3ae9
Reviewed-on: https://go-review.googlesource.com/34876
Reviewed-by: Ian Lance Taylor <iant@golang.org>

@golang golang locked and limited conversation to collaborators Jun 22, 2018

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.