net: update documentation on methods of IPConn

This change simplifies the documentation on methods of IPConn and adds
a reference to golang.org/x/net/ipv{4,6} packages to the documentation
on {Read,Write}MsgIP methods.

Change-Id: Ie07a853288940e0fef6a417ffc8d0c3d444c21cd
Reviewed-on: https://go-review.googlesource.com/44911
Run-TryBot: Mikio Hara <mikioh.mikioh@gmail.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>

1 files changed, 12 insertions, 18 deletions

diff --git a/src/net/iprawsock.go b/src/net/iprawsock.go
index 2ff2f508d4..00f59631a2 100644
--- a/src/net/iprawsock.go
+++ b/src/net/iprawsock.go
@@ -109,13 +109,7 @@ func (c *IPConn) SyscallConn() (syscall.RawConn, error) {
 	return newRawConn(c.fd)
 }
 
-// ReadFromIP reads an IP packet from c, copying the payload into b.
-// It returns the number of bytes copied into b and the return address
-// that was on the packet.
-//
-// ReadFromIP can be made to time out and return an error with
-// Timeout() == true after a fixed time limit; see SetDeadline and
-// SetReadDeadline.
+// ReadFromIP acts like ReadFrom but returns an IPAddr.
 func (c *IPConn) ReadFromIP(b []byte) (int, *IPAddr, error) {
 	if !c.ok() {
 		return 0, nil, syscall.EINVAL
@@ -142,10 +136,13 @@ func (c *IPConn) ReadFrom(b []byte) (int, Addr, error) {
 	return n, addr, err
 }
 
-// ReadMsgIP reads a packet from c, copying the payload into b and the
-// associated out-of-band data into oob. It returns the number of
+// ReadMsgIP reads a message from c, copying the payload into b and
+// the associated out-of-band data into oob. It returns the number of
 // bytes copied into b, the number of bytes copied into oob, the flags
-// that were set on the packet and the source address of the packet.
+// that were set on the message and the source address of the message.
+//
+// The packages golang.org/x/net/ipv4 and golang.org/x/net/ipv6 can be
+// used to manipulate IP-level socket options in oob.
 func (c *IPConn) ReadMsgIP(b, oob []byte) (n, oobn, flags int, addr *IPAddr, err error) {
 	if !c.ok() {
 		return 0, 0, 0, nil, syscall.EINVAL
@@ -157,13 +154,7 @@ func (c *IPConn) ReadMsgIP(b, oob []byte) (n, oobn, flags int, addr *IPAddr, err
 	return
 }
 
-// WriteToIP writes an IP packet to addr via c, copying the payload
-// from b.
-//
-// WriteToIP can be made to time out and return an error with
-// Timeout() == true after a fixed time limit; see SetDeadline and
-// SetWriteDeadline. On packet-oriented connections, write timeouts
-// are rare.
+// WriteToIP acts like WriteTo but takes an IPAddr.
 func (c *IPConn) WriteToIP(b []byte, addr *IPAddr) (int, error) {
 	if !c.ok() {
 		return 0, syscall.EINVAL
@@ -191,9 +182,12 @@ func (c *IPConn) WriteTo(b []byte, addr Addr) (int, error) {
 	return n, err
 }
 
-// WriteMsgIP writes a packet to addr via c, copying the payload from
+// WriteMsgIP writes a message to addr via c, copying the payload from
 // b and the associated out-of-band data from oob. It returns the
 // number of payload and out-of-band bytes written.
+//
+// The packages golang.org/x/net/ipv4 and golang.org/x/net/ipv6 can be
+// used to manipulate IP-level socket options in oob.
 func (c *IPConn) WriteMsgIP(b, oob []byte, addr *IPAddr) (n, oobn int, err error) {
 	if !c.ok() {
 		return 0, 0, syscall.EINVAL