From f19a4e43982dc512a929d113daf51c6552981cff Mon Sep 17 00:00:00 2001 From: Neil Alexander Date: Fri, 29 Mar 2019 18:18:31 +0000 Subject: [PATCH] More godoc improvements --- src/multicast/multicast.go | 9 +++++++++ src/tuntap/tun.go | 35 ++++++++++++++++++++++------------- src/yggdrasil/router.go | 10 +++++++++- src/yggdrasil/tcp.go | 4 ++++ 4 files changed, 44 insertions(+), 14 deletions(-) diff --git a/src/multicast/multicast.go b/src/multicast/multicast.go index c6756808..4e5bc4b1 100644 --- a/src/multicast/multicast.go +++ b/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 } diff --git a/src/tuntap/tun.go b/src/tuntap/tun.go index 5a247bff..600d3d76 100644 --- a/src/tuntap/tun.go +++ b/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 -// as 65535, depending on platform, but is never lower than 1280. +// DefaultMTU gets the default TUN/TAP interface MTU for your platform. This can +// 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 -// can be as high as 65535, depending on platform, but is never lower than 1280. +// MaximumMTU returns the maximum supported TUN/TAP interface MTU for your +// 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 -// the read/write goroutines to handle packets on that interface. +// Start the setup process for the TUN/TAP adapter. If successful, starts the +// 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 diff --git a/src/yggdrasil/router.go b/src/yggdrasil/router.go index 9130f554..aee92244 100644 --- a/src/yggdrasil/router.go +++ b/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 diff --git a/src/yggdrasil/tcp.go b/src/yggdrasil/tcp.go index b9681fc2..4361ec82 100644 --- a/src/yggdrasil/tcp.go +++ b/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