code review 8063043: net: update documentation for ListenTCP, ListenUDP

net: update documentation for ListenTCP, ListenUDP

Adds the missing wildcard port assignment description to ListenUDP.
Also updates the wildcard port description on ListenTCP.

[mikio, 2013-03-28 02:33:33]

Hello golang-dev@googlegroups.com (cc: golang-dev@googlegroups.com),

I'd like you to review this change to
https://code.google.com/p/go

[dave_cheney.net, 2013-03-28 03:39:59]

Thanks. I think this is pretty close, but if we're wordsmithing the
documentation, it would pay to do another round of review.

https://codereview.appspot.com/8063043/diff/4001/src/pkg/net/tcpsock_plan9.go
File src/pkg/net/tcpsock_plan9.go (right):

https://codereview.appspot.com/8063043/diff/4001/src/pkg/net/tcpsock_plan9.go...
src/pkg/net/tcpsock_plan9.go:166: // ListenTCP announces on the TCP address
laddr and returns a TCP
How about 

// ListenTCP binds to the TCP address laddr and returns ...

That is what it does right ? It binds a socket to laddr, and that socket can be
used to pass to accept(2).

https://codereview.appspot.com/8063043/diff/4001/src/pkg/net/tcpsock_plan9.go...
src/pkg/net/tcpsock_plan9.go:167: // listener.  The net must be "tcp", "tcp4",
or "tcp6".  If laddr has
// If laddr has a port of 0, the operating system will choose a port on laddr to
bind too.

https://codereview.appspot.com/8063043/diff/4001/src/pkg/net/tcpsock_posix.go
File src/pkg/net/tcpsock_posix.go (right):

https://codereview.appspot.com/8063043/diff/4001/src/pkg/net/tcpsock_posix.go...
src/pkg/net/tcpsock_posix.go:275: // ListenTCP announces on the TCP address
laddr and returns a TCP
please see tcpsock_plan9.go

https://codereview.appspot.com/8063043/diff/4001/src/pkg/net/udpsock_plan9.go
File src/pkg/net/udpsock_plan9.go (right):

https://codereview.appspot.com/8063043/diff/4001/src/pkg/net/udpsock_plan9.go...
src/pkg/net/udpsock_plan9.go:169: // UDPConn to retrieve the chosen address. 
The returned connection's
see previous for alternative description of binding to port 0.

[r, 2013-03-28 03:41:51]

https://codereview.appspot.com/8063043/diff/4001/src/pkg/net/tcpsock_plan9.go
File src/pkg/net/tcpsock_plan9.go (right):

https://codereview.appspot.com/8063043/diff/4001/src/pkg/net/tcpsock_plan9.go...
src/pkg/net/tcpsock_plan9.go:167: // listener.  The net must be "tcp", "tcp4",
or "tcp6".  If laddr has
it was fine as is, or
The net argument must be

https://codereview.appspot.com/8063043/diff/4001/src/pkg/net/tcpsock_plan9.go...
src/pkg/net/tcpsock_plan9.go:169: // can use Addr method on TCPListener to
retrieve the chosen address.
the Addr method of TCP Listener

same in the other files

https://codereview.appspot.com/8063043/diff/4001/src/pkg/net/udpsock_plan9.go
File src/pkg/net/udpsock_plan9.go (right):

https://codereview.appspot.com/8063043/diff/4001/src/pkg/net/udpsock_plan9.go...
src/pkg/net/udpsock_plan9.go:168: // some available port.  The caller can use
LocalAddr method on
If laddr has a port of 0, ListenUDP will choose an available port. The LocalAddr
method of the returned UDPConn can be used to discover the port.

same in the others

[mikio, 2013-03-28 06:06:02]

Thank both of you, will update tonight.

On 2013/03/28 03:39:59, dfc wrote:

> How about 
> 
> // ListenTCP binds to the TCP address laddr and returns ...
> 
> That is what it does right ? It binds a socket to laddr, and that socket can
be
> used to pass to accept(2).

bind just gives a name to the socket. a name represents the information
could be used for delivering user data. it usually consists of 5-tuple in 
the internet protocol family namespaces.

listen starts announcing the given name to the protocol stuff, and 
configures num of backlogs.

[mikio, 2013-03-28 14:24:32]

Hello golang-dev@googlegroups.com, dave@cheney.net, r@golang.org (cc:
golang-dev@googlegroups.com),

Please take another look.

[r, 2013-03-28 17:16:56]

LGTM but wait for dave cheney

[dave_cheney.net, 2013-03-29 03:38:01]

LGTM with the two minor suggestions below.

https://codereview.appspot.com/8063043/diff/15001/src/pkg/net/tcpsock_plan9.go
File src/pkg/net/tcpsock_plan9.go (right):

https://codereview.appspot.com/8063043/diff/15001/src/pkg/net/tcpsock_plan9.g...
src/pkg/net/tcpsock_plan9.go:167: // listener.  Net must be "tcp", "tcp4", or
"tcp6".  If laddr has a
see tcpsock_posix.go

https://codereview.appspot.com/8063043/diff/15001/src/pkg/net/tcpsock_posix.go
File src/pkg/net/tcpsock_posix.go (right):

https://codereview.appspot.com/8063043/diff/15001/src/pkg/net/tcpsock_posix.g...
src/pkg/net/tcpsock_posix.go:277: // port of 0, it means to listen on some
available port.  The caller
For consistency with the ListenUDP comment I suggest this

// If laddr has a port of 0, ListenTCP will choose an available port.

[mikio, 2013-03-29 06:06:52]

*** Submitted as https://code.google.com/p/go/source/detail?r=486b88b8eabf ***

net: update documentation for ListenTCP, ListenUDP

Adds the missing wildcard port assignment description to ListenUDP.
Also updates the wildcard port description on ListenTCP.

R=golang-dev, dave, r
CC=golang-dev
https://codereview.appspot.com/8063043

https://codereview.appspot.com/8063043/diff/15001/src/pkg/net/tcpsock_plan9.go
File src/pkg/net/tcpsock_plan9.go (right):

https://codereview.appspot.com/8063043/diff/15001/src/pkg/net/tcpsock_plan9.g...
src/pkg/net/tcpsock_plan9.go:167: // listener.  Net must be "tcp", "tcp4", or
"tcp6".  If laddr has a
On 2013/03/29 03:38:02, dfc wrote:
> see tcpsock_posix.go

Done.

https://codereview.appspot.com/8063043/diff/15001/src/pkg/net/tcpsock_posix.go
File src/pkg/net/tcpsock_posix.go (right):

https://codereview.appspot.com/8063043/diff/15001/src/pkg/net/tcpsock_posix.g...
src/pkg/net/tcpsock_posix.go:277: // port of 0, it means to listen on some
available port.  The caller
On 2013/03/29 03:38:02, dfc wrote:
> For consistency with the ListenUDP comment I suggest this
> 
> // If laddr has a port of 0, ListenTCP will choose an available port.

Done.