libnetwork/osl: add godoc to networkNamespace

Copying the descriptions from the Sandbox, Info, NeighborOptionSetter,
and IfaceOptionSetter interfaces that it implements.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

libnetwork/osl/interface_linux.go

@@ -179,6 +179,11 @@ func (n *networkNamespace) findDst(srcName string, isBridge bool) string {
 	return ""
 }
 
+// AddInterface adds an existing Interface to the sandbox. The operation will rename
+// from the Interface SrcName to DstName as it moves, and reconfigure the
+// interface according to the specified settings. The caller is expected
+// to only provide a prefix for DstName. The AddInterface api will auto-generate
+// an appropriate suffix for the DstName to disambiguate.
 func (n *networkNamespace) AddInterface(srcName, dstPrefix string, options ...IfaceOption) error {
 	i := &nwIface{
 		srcName: srcName,

libnetwork/osl/namespace_linux.go

@@ -313,9 +313,10 @@ func createNamespaceFile(path string) (err error) {
 	return err
 }
 
-// The networkNamespace type is the linux implementation of the Sandbox
-// interface. It represents a linux network namespace, and moves an interface
-// into it when called on method AddInterface or sets the gateway etc.
+// networkNamespace represents a network sandbox. It represents a Linux network
+// namespace, and moves an interface into it when called on method AddInterface
+// or sets the gateway etc. It holds a list of Interfaces, routes etc., and more
+// can be added dynamically.
 type networkNamespace struct {
 	path         string
 	iFaces       []*nwIface
@@ -330,6 +331,10 @@ type networkNamespace struct {
 	sync.Mutex
 }
 
+// Interfaces returns the collection of Interface previously added with the AddInterface
+// method. Note that this doesn't include network interfaces added in any
+// other way (such as the default loopback interface which is automatically
+// created on creation of a sandbox).
 func (n *networkNamespace) Interfaces() []Interface {
 	ifaces := make([]Interface, len(n.iFaces))
 	for i, iface := range n.iFaces {
@@ -338,10 +343,12 @@ func (n *networkNamespace) Interfaces() []Interface {
 	return ifaces
 }
 
+// InterfaceOptions an interface with methods to set interface options.
 func (n *networkNamespace) InterfaceOptions() IfaceOptionSetter {
 	return n
 }
 
+// NeighborOptions returns an interface with methods to set neighbor options.
 func (n *networkNamespace) NeighborOptions() NeighborOptionSetter {
 	return n
 }
@@ -354,10 +361,12 @@ func (n *networkNamespace) loopbackUp() error {
 	return n.nlHandle.LinkSetUp(iface)
 }
 
+// GetLoopbackIfaceName returns the name of the loopback interface
 func (n *networkNamespace) GetLoopbackIfaceName() string {
 	return "lo"
 }
 
+// AddAliasIP adds the passed IP address to the named interface
 func (n *networkNamespace) AddAliasIP(ifName string, ip *net.IPNet) error {
 	iface, err := n.nlHandle.LinkByName(ifName)
 	if err != nil {
@@ -366,6 +375,7 @@ func (n *networkNamespace) AddAliasIP(ifName string, ip *net.IPNet) error {
 	return n.nlHandle.AddrAdd(iface, &netlink.Addr{IPNet: ip})
 }
 
+// RemoveAliasIP removes the passed IP address from the named interface
 func (n *networkNamespace) RemoveAliasIP(ifName string, ip *net.IPNet) error {
 	iface, err := n.nlHandle.LinkByName(ifName)
 	if err != nil {
@@ -374,6 +384,8 @@ func (n *networkNamespace) RemoveAliasIP(ifName string, ip *net.IPNet) error {
 	return n.nlHandle.AddrDel(iface, &netlink.Addr{IPNet: ip})
 }
 
+// DisableARPForVIP disables ARP replies and requests for VIP addresses
+// on a particular interface.
 func (n *networkNamespace) DisableARPForVIP(srcName string) (Err error) {
 	dstName := ""
 	for _, i := range n.Interfaces() {
@@ -404,6 +416,7 @@ func (n *networkNamespace) DisableARPForVIP(srcName string) (Err error) {
 	return
 }
 
+// InvokeFunc invoke a function in the network namespace.
 func (n *networkNamespace) InvokeFunc(f func()) error {
 	path := n.nsPath()
 	newNS, err := netns.GetFromPath(path)
@@ -455,10 +468,12 @@ func (n *networkNamespace) nsPath() string {
 	return n.path
 }
 
+// Key returns the path where the network namespace is mounted.
 func (n *networkNamespace) Key() string {
 	return n.path
 }
 
+// Destroy destroys the sandbox.
 func (n *networkNamespace) Destroy() error {
 	if n.nlHandle != nil {
 		n.nlHandle.Close()
@@ -474,7 +489,7 @@ func (n *networkNamespace) Destroy() error {
 	return nil
 }
 
-// Restore restore the network namespace
+// Restore restores the network namespace.
 func (n *networkNamespace) Restore(ifsopt map[Iface][]IfaceOption, routes []*types.StaticRoute, gw net.IP, gw6 net.IP) error {
 	// restore interfaces
 	for name, opts := range ifsopt {
@@ -602,7 +617,7 @@ func (n *networkNamespace) checkLoV6() {
 	n.loV6Enabled = enable
 }
 
-// ApplyOSTweaks applies linux configs on the sandbox
+// ApplyOSTweaks applies operating system specific knobs on the sandbox.
 func (n *networkNamespace) ApplyOSTweaks(types []SandboxType) {
 	for _, t := range types {
 		switch t {

libnetwork/osl/neigh_linux.go

@@ -42,6 +42,7 @@ func (n *networkNamespace) findNeighbor(dstIP net.IP, dstMac net.HardwareAddr) *
 	return nil
 }
 
+// DeleteNeighbor deletes neighbor entry from the sandbox.
 func (n *networkNamespace) DeleteNeighbor(dstIP net.IP, dstMac net.HardwareAddr, osDelete bool) error {
 	var (
 		iface netlink.Link
@@ -119,6 +120,7 @@ func (n *networkNamespace) DeleteNeighbor(dstIP net.IP, dstMac net.HardwareAddr,
 	return nil
 }
 
+// AddNeighbor adds a neighbor entry into the sandbox.
 func (n *networkNamespace) AddNeighbor(dstIP net.IP, dstMac net.HardwareAddr, force bool, options ...NeighOption) error {
 	var (
 		iface                  netlink.Link

libnetwork/osl/options_linux.go

@@ -10,12 +10,16 @@ func (nh *neigh) processNeighOptions(options ...NeighOption) {
 	}
 }
 
+// LinkName returns an option setter to set the srcName of the link that should
+// be used in the neighbor entry
 func (n *networkNamespace) LinkName(name string) NeighOption {
 	return func(nh *neigh) {
 		nh.linkName = name
 	}
 }
 
+// Family returns an option setter to set the address family for the neighbor
+// entry. eg. AF_BRIDGE
 func (n *networkNamespace) Family(family int) NeighOption {
 	return func(nh *neigh) {
 		nh.family = family
@@ -30,42 +34,51 @@ func (i *nwIface) processInterfaceOptions(options ...IfaceOption) {
 	}
 }
 
+// Bridge returns an option setter to set if the interface is a bridge.
 func (n *networkNamespace) Bridge(isBridge bool) IfaceOption {
 	return func(i *nwIface) {
 		i.bridge = isBridge
 	}
 }
 
+// Master returns an option setter to set the master interface if any for this
+// interface. The master interface name should refer to the srcname of a
+// previously added interface of type bridge.
 func (n *networkNamespace) Master(name string) IfaceOption {
 	return func(i *nwIface) {
 		i.master = name
 	}
 }
 
+// MacAddress returns an option setter to set the MAC address.
 func (n *networkNamespace) MacAddress(mac net.HardwareAddr) IfaceOption {
 	return func(i *nwIface) {
 		i.mac = mac
 	}
 }
 
+// Address returns an option setter to set IPv4 address.
 func (n *networkNamespace) Address(addr *net.IPNet) IfaceOption {
 	return func(i *nwIface) {
 		i.address = addr
 	}
 }
 
+// AddressIPv6 returns an option setter to set IPv6 address.
 func (n *networkNamespace) AddressIPv6(addr *net.IPNet) IfaceOption {
 	return func(i *nwIface) {
 		i.addressIPv6 = addr
 	}
 }
 
+// LinkLocalAddresses returns an option setter to set the link-local IP addresses.
 func (n *networkNamespace) LinkLocalAddresses(list []*net.IPNet) IfaceOption {
 	return func(i *nwIface) {
 		i.llAddrs = list
 	}
 }
 
+// Routes returns an option setter to set interface routes.
 func (n *networkNamespace) Routes(routes []*net.IPNet) IfaceOption {
 	return func(i *nwIface) {
 		i.routes = routes

libnetwork/osl/route_linux.go

@@ -8,6 +8,7 @@ import (
 	"github.com/vishvananda/netlink"
 )
 
+// Gateway returns the IPv4 gateway for the sandbox.
 func (n *networkNamespace) Gateway() net.IP {
 	n.Lock()
 	defer n.Unlock()
@@ -15,6 +16,7 @@ func (n *networkNamespace) Gateway() net.IP {
 	return n.gw
 }
 
+// GatewayIPv6 returns the IPv6 gateway for the sandbox.
 func (n *networkNamespace) GatewayIPv6() net.IP {
 	n.Lock()
 	defer n.Unlock()
@@ -22,6 +24,9 @@ func (n *networkNamespace) GatewayIPv6() net.IP {
 	return n.gwv6
 }
 
+// StaticRoutes returns additional static routes for the sandbox. Note that
+// directly connected routes are stored on the particular interface they
+// refer to.
 func (n *networkNamespace) StaticRoutes() []*types.StaticRoute {
 	n.Lock()
 	defer n.Unlock()
@@ -47,6 +52,7 @@ func (n *networkNamespace) setGatewayIPv6(gwv6 net.IP) {
 	n.Unlock()
 }
 
+// SetGateway sets the default IPv4 gateway for the sandbox.
 func (n *networkNamespace) SetGateway(gw net.IP) error {
 	// Silently return if the gateway is empty
 	if len(gw) == 0 {
@@ -61,6 +67,7 @@ func (n *networkNamespace) SetGateway(gw net.IP) error {
 	return err
 }
 
+// UnsetGateway the previously set default IPv4 gateway in the sandbox.
 func (n *networkNamespace) UnsetGateway() error {
 	gw := n.Gateway()
 
@@ -140,6 +147,7 @@ func (n *networkNamespace) removeRoute(path string, dest *net.IPNet, nh net.IP)
 	})
 }
 
+// SetGatewayIPv6 sets the default IPv6 gateway for the sandbox.
 func (n *networkNamespace) SetGatewayIPv6(gwv6 net.IP) error {
 	// Silently return if the gateway is empty
 	if len(gwv6) == 0 {
@@ -154,6 +162,7 @@ func (n *networkNamespace) SetGatewayIPv6(gwv6 net.IP) error {
 	return err
 }
 
+// UnsetGatewayIPv6 unsets the previously set default IPv6 gateway in the sandbox.
 func (n *networkNamespace) UnsetGatewayIPv6() error {
 	gwv6 := n.GatewayIPv6()
 
@@ -172,6 +181,7 @@ func (n *networkNamespace) UnsetGatewayIPv6() error {
 	return err
 }
 
+// AddStaticRoute adds a static route to the sandbox.
 func (n *networkNamespace) AddStaticRoute(r *types.StaticRoute) error {
 	err := n.programRoute(n.nsPath(), r.Destination, r.NextHop)
 	if err == nil {
@@ -182,6 +192,7 @@ func (n *networkNamespace) AddStaticRoute(r *types.StaticRoute) error {
 	return err
 }
 
+// RemoveStaticRoute removes a static route from the sandbox.
 func (n *networkNamespace) RemoveStaticRoute(r *types.StaticRoute) error {
 	err := n.removeRoute(n.nsPath(), r.Destination, r.NextHop)
 	if err == nil {