More godoc improvements

src/multicast/multicast.go

@@ -14,6 +14,10 @@ import (
 	"golang.org/x/net/ipv6"
 )
 
+// Multicast represents the multicast advertisement and discovery mechanism used
+// by Yggdrasil to find peers on the same subnet. When a beacon is received on a
+// configured multicast interface, Yggdrasil will attempt to peer with that node
+// automatically.
 type Multicast struct {
 	core        *yggdrasil.Core
 	config      *config.NodeState
@@ -25,6 +29,7 @@ type Multicast struct {
 	listenPort  uint16
 }
 
+// Init prepares the multicast interface for use.
 func (m *Multicast) Init(core *yggdrasil.Core, state *config.NodeState, log *log.Logger, options interface{}) error {
 	m.core = core
 	m.config = state
@@ -47,6 +52,9 @@ func (m *Multicast) Init(core *yggdrasil.Core, state *config.NodeState, log *log
 	return nil
 }
 
+// Start starts the multicast interface. This launches goroutines which will
+// listen for multicast beacons from other hosts and will advertise multicast
+// beacons out to the network.
 func (m *Multicast) Start() error {
 	if len(m.interfaces()) == 0 {
 		m.log.Infoln("Multicast discovery is disabled")
@@ -76,6 +84,7 @@ func (m *Multicast) Start() error {
 	return nil
 }
 
+// Stop is not implemented for multicast yet.
 func (m *Multicast) Stop() error {
 	return nil
 }

src/tuntap/tun.go

@@ -27,7 +27,10 @@ import (
 const tun_IPv6_HEADER_LENGTH = 40
 const tun_ETHER_HEADER_LENGTH = 14
 
-// Represents a running TUN/TAP interface.
+// TunAdapter represents a running TUN/TAP interface and extends the
+// yggdrasil.Adapter type. In order to use the TUN/TAP adapter with Yggdrasil,
+// you should pass this object to the yggdrasil.SetRouterAdapter() function
+// before calling yggdrasil.Start().
 type TunAdapter struct {
 	yggdrasil.Adapter
 	addr   address.Address
@@ -50,44 +53,50 @@ func getSupportedMTU(mtu int) int {
 	return mtu
 }
 
-// Get the adapter name
+// Name returns the name of the adapter, e.g. "tun0". On Windows, this may
+// return a canonical adapter name instead.
 func (tun *TunAdapter) Name() string {
 	return tun.iface.Name()
 }
 
-// Get the adapter MTU
+// MTU gets the adapter's MTU. This can range between 1280 and 65535, although
+// the maximum value is determined by your platform. The returned value will
+// never exceed that of MaximumMTU().
 func (tun *TunAdapter) MTU() int {
 	return getSupportedMTU(tun.mtu)
 }
 
-// Get the adapter mode
+// IsTAP returns true if the adapter is a TAP adapter (Layer 2) or false if it
+// is a TUN adapter (Layer 3).
 func (tun *TunAdapter) IsTAP() bool {
 	return tun.iface.IsTAP()
 }
 
-// Gets the default TUN/TAP interface name for your platform.
+// DefaultName gets the default TUN/TAP interface name for your platform.
 func DefaultName() string {
 	return defaults.GetDefaults().DefaultIfName
 }
 
-// Gets the default TUN/TAP interface MTU for your platform. This can be as high
+// DefaultMTU gets the default TUN/TAP interface MTU for your platform. This can
-// as 65535, depending on platform, but is never lower than 1280.
+// be as high as MaximumMTU(), depending on platform, but is never lower than 1280.
 func DefaultMTU() int {
 	return defaults.GetDefaults().DefaultIfMTU
 }
 
-// Gets the default TUN/TAP interface mode for your platform.
+// DefaultIsTAP returns true if the default adapter mode for the current
+// platform is TAP (Layer 2) and returns false for TUN (Layer 3).
 func DefaultIsTAP() bool {
 	return defaults.GetDefaults().DefaultIfTAPMode
 }
 
-// Gets the maximum supported TUN/TAP interface MTU for your platform. This
+// MaximumMTU returns the maximum supported TUN/TAP interface MTU for your
-// can be as high as 65535, depending on platform, but is never lower than 1280.
+// platform. This can be as high as 65535, depending on platform, but is never
+// lower than 1280.
 func MaximumMTU() int {
 	return defaults.GetDefaults().MaximumIfMTU
 }
 
-// Initialises the TUN/TAP adapter.
+// Init initialises the TUN/TAP adapter.
 func (tun *TunAdapter) Init(config *config.NodeState, log *log.Logger, send chan<- []byte, recv <-chan []byte, reject <-chan yggdrasil.RejectedPacket) {
 	tun.config = config
 	tun.log = log
@@ -111,8 +120,8 @@ func (tun *TunAdapter) Init(config *config.NodeState, log *log.Logger, send chan
 	}()
 }
 
-// Starts the setup process for the TUN/TAP adapter, and if successful, starts
+// Start the setup process for the TUN/TAP adapter. If successful, starts the
-// the read/write goroutines to handle packets on that interface.
+// read/write goroutines to handle packets on that interface.
 func (tun *TunAdapter) Start(a address.Address, s address.Subnet) error {
 	tun.addr = a
 	tun.subnet = s

src/yggdrasil/router.go

@@ -57,13 +57,21 @@ type router_recvPacket struct {
 	sinfo *sessionInfo
 }
 
+// RejectedPacketReason is the type code used to represent the reason that a
+// packet was rejected.
 type RejectedPacketReason int
 
 const (
-	// The router rejected the packet because it is too big for the session
+	// The router rejected the packet because it exceeds the session MTU for the
+	// given destination. In TUN/TAP, this results in the generation of an ICMPv6
+	// Packet Too Big message.
 	PacketTooBig = 1 + iota
 )
 
+// RejectedPacket represents a rejected packet from the router. This is passed
+// back to the adapter so that the adapter can respond appropriately, e.g. in
+// the case of TUN/TAP, a "PacketTooBig" reason can be used to generate an
+// ICMPv6 Packet Too Big response.
 type RejectedPacket struct {
 	Reason RejectedPacketReason
 	Packet []byte

src/yggdrasil/tcp.go

@@ -41,6 +41,10 @@ type tcp struct {
 	conns       map[linkInfo](chan struct{})
 }
 
+// TcpListener is a stoppable TCP listener interface. These are typically
+// returned from calls to the ListenTCP() function and are also used internally
+// to represent listeners created by the "Listen" configuration option and for
+// multicast interfaces.
 type TcpListener struct {
 	Listener net.Listener
 	Stop     chan bool