x/net/ipv6: update package documentation

LGTM=iant
R=iant
CC=golang-codereviews
https://golang.org/cl/177840043

ipv6/dgramopt_posix.go

@@ -93,14 +93,15 @@ func (c *dgramOpt) SetMulticastLoopback(on bool) error {
 	return setInt(fd, &sockOpts[ssoMulticastLoopback], boolint(on))
 }
 
-// JoinGroup joins the group address group on the interface ifi. By
-// default all sources that can cast data to group are accepted. It's
-// possible to mute and unmute data transmission from a specific
+// JoinGroup joins the group address group on the interface ifi.
+// By default all sources that can cast data to group are accepted.
+// It's possible to mute and unmute data transmission from a specific
 // source by using ExcludeSourceSpecificGroup and
 // IncludeSourceSpecificGroup.
-// It uses the system assigned multicast interface when ifi is nil,
-// although this is not recommended because the assignment depends on
-// platforms and sometimes it might require routing configuration.
+// JoinGroup uses the system assigned multicast interface when ifi is
+// nil, although this is not recommended because the assignment
+// depends on platforms and sometimes it might require routing
+// configuration.
 func (c *dgramOpt) JoinGroup(ifi *net.Interface, group net.Addr) error {
 	if !c.ok() {
 		return syscall.EINVAL
@@ -116,9 +117,9 @@ func (c *dgramOpt) JoinGroup(ifi *net.Interface, group net.Addr) error {
 	return setGroup(fd, &sockOpts[ssoJoinGroup], ifi, grp)
 }
 
-// LeaveGroup leaves the group address group on the interface ifi.
-// It's allowed to leave the group which is formed by
-// JoinSourceSpecificGroup for convenience.
+// LeaveGroup leaves the group address group on the interface ifi
+// regardless of whether the group is any-source group or
+// source-specific group.
 func (c *dgramOpt) LeaveGroup(ifi *net.Interface, group net.Addr) error {
 	if !c.ok() {
 		return syscall.EINVAL
@@ -134,11 +135,12 @@ func (c *dgramOpt) LeaveGroup(ifi *net.Interface, group net.Addr) error {
 	return setGroup(fd, &sockOpts[ssoLeaveGroup], ifi, grp)
 }
 
-// JoinSourceSpecificGroup joins the source-specific group consisting
-// group and source on the interface ifi. It uses the system assigned
-// multicast interface when ifi is nil, although this is not
-// recommended because the assignment depends on platforms and
-// sometimes it might require routing configuration.
+// JoinSourceSpecificGroup joins the source-specific group comprising
+// group and source on the interface ifi.
+// JoinSourceSpecificGroup uses the system assigned multicast
+// interface when ifi is nil, although this is not recommended because
+// the assignment depends on platforms and sometimes it might require
+// routing configuration.
 func (c *dgramOpt) JoinSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error {
 	if !c.ok() {
 		return syscall.EINVAL
@@ -180,8 +182,8 @@ func (c *dgramOpt) LeaveSourceSpecificGroup(ifi *net.Interface, group, source ne
 }
 
 // ExcludeSourceSpecificGroup excludes the source-specific group from
-// the already joined groups by either JoinGroup or
-// JoinSourceSpecificGroup on the interface ifi.
+// the already joined any-source groups by JoinGroup on the interface
+// ifi.
 func (c *dgramOpt) ExcludeSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error {
 	if !c.ok() {
 		return syscall.EINVAL

ipv6/dgramopt_stub.go

@@ -44,30 +44,32 @@ func (c *dgramOpt) SetMulticastLoopback(on bool) error {
 	return errOpNoSupport
 }
 
-// JoinGroup joins the group address group on the interface ifi. By
-// default all sources that can cast data to group are accepted. It's
-// possible to mute and unmute data transmission from a specific
+// JoinGroup joins the group address group on the interface ifi.
+// By default all sources that can cast data to group are accepted.
+// It's possible to mute and unmute data transmission from a specific
 // source by using ExcludeSourceSpecificGroup and
 // IncludeSourceSpecificGroup.
-// It uses the system assigned multicast interface when ifi is nil,
-// although this is not recommended because the assignment depends on
-// platforms and sometimes it might require routing configuration.
+// JoinGroup uses the system assigned multicast interface when ifi is
+// nil, although this is not recommended because the assignment
+// depends on platforms and sometimes it might require routing
+// configuration.
 func (c *dgramOpt) JoinGroup(ifi *net.Interface, group net.Addr) error {
 	return errOpNoSupport
 }
 
-// LeaveGroup leaves the group address group on the interface ifi.
-// It's allowed to leave the group which is formed by
-// JoinSourceSpecificGroup for convenience.
+// LeaveGroup leaves the group address group on the interface ifi
+// regardless of whether the group is any-source group or
+// source-specific group.
 func (c *dgramOpt) LeaveGroup(ifi *net.Interface, group net.Addr) error {
 	return errOpNoSupport
 }
 
-// JoinSourceSpecificGroup joins the source-specific group consisting
-// group and source on the interface ifi. It uses the system assigned
-// multicast interface when ifi is nil, although this is not
-// recommended because the assignment depends on platforms and
-// sometimes it might require routing configuration.
+// JoinSourceSpecificGroup joins the source-specific group comprising
+// group and source on the interface ifi.
+// JoinSourceSpecificGroup uses the system assigned multicast
+// interface when ifi is nil, although this is not recommended because
+// the assignment depends on platforms and sometimes it might require
+// routing configuration.
 func (c *dgramOpt) JoinSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error {
 	return errOpNoSupport
 }
@@ -79,8 +81,8 @@ func (c *dgramOpt) LeaveSourceSpecificGroup(ifi *net.Interface, group, source ne
 }
 
 // ExcludeSourceSpecificGroup excludes the source-specific group from
-// the already joined groups by either JoinGroup or
-// JoinSourceSpecificGroup on the interface ifi.
+// the already joined any-source groups by JoinGroup on the interface
+// ifi.
 func (c *dgramOpt) ExcludeSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error {
 	return errOpNoSupport
 }

ipv6/doc.go

@@ -34,7 +34,7 @@
 //			defer c.Close()
 //
 // The outgoing packets will be labeled DiffServ assured forwarding
-// class 1 low drop precedence, as known as AF11 packets.
+// class 1 low drop precedence, known as AF11 packets.
 //
 //			if err := ipv6.NewConn(c).SetTrafficClass(DiffServAF11); err != nil {
 //				// error handling
@@ -191,4 +191,44 @@
 //	if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff01::114")}); err != nil {
 //		// error handling
 //	}
+//
+//
+// Source-specific multicasting
+//
+// An application that uses PacketConn on MLDv2 supported platform is
+// able to join source-specific multicast groups as described in RFC
+// 3678.  The application may use JoinSourceSpecificGroup and
+// LeaveSourceSpecificGroup for the operation known as "include" mode,
+//
+//	ssmgroup := net.UDPAddr{IP: net.ParseIP("ff32::8000:9")}
+//	ssmsource := net.UDPAddr{IP: net.ParseIP("fe80::cafe")}
+//	if err := p.JoinSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
+//		// error handling
+//	}
+//	if err := p.LeaveSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
+//		// error handling
+//	}
+//
+// or JoinGroup, ExcludeSourceSpecificGroup,
+// IncludeSourceSpecificGroup and LeaveGroup for the operation known
+// as "exclude" mode.
+//
+//	exclsource := net.UDPAddr{IP: net.ParseIP("fe80::dead")}
+//	if err := p.JoinGroup(en0, &ssmgroup); err != nil {
+//		// error handling
+//	}
+//	if err := p.ExcludeSourceSpecificGroup(en0, &ssmgroup, &exclsource); err != nil {
+//		// error handling
+//	}
+//	if err := p.LeaveGroup(en0, &ssmgroup); err != nil {
+//		// error handling
+//	}
+//
+// Note that it depends on each platform implementation what happens
+// when an application which runs on MLDv2 unsupported platform uses
+// JoinSourceSpecificGroup and LeaveSourceSpecificGroup.
+// In general the platform tries to fall back to conversations using
+// MLDv1 and starts to listen to multicast traffic.
+// In the fallback case, ExcludeSourceSpecificGroup and
+// IncludeSourceSpecificGroup may return an error.
 package ipv6