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

Jump to bottom

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

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

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

mikioh opened this issue Nov 17, 2016 · 9 comments
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Unplanned

Comments

@mikioh
Copy link
Contributor

mikioh 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 The path to resolution is known, but the work has not been done. label Nov 17, 2016
@quentinmit
Copy link
Contributor

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
Copy link
Contributor

as 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
Copy link
Contributor

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
Copy link
Contributor Author

mikioh commented Nov 19, 2016 •
edited

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
Copy link
Contributor

as 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
Copy link
Contributor Author

mikioh 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
Copy link
Contributor Author

mikioh 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
Copy link

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

@gopherbot
Copy link

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

gopherbot pushed a commit that referenced this issue Jun 22, 2017
@cixtor
net: update documentation on Listen and ListenPacket
424b065 
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.
Assignees
No one assigned
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Unplanned
Development

No branches or pull requests
5 participants
@bradfitz @mikioh @quentinmit @as @gopherbot