add comments, fiddle with function publicity

5 files changed, 34 insertions, 15 deletions

diff --git a/influxdb.go b/influxdb.go
index 992bef3..7dd42bb 100644
--- a/influxdb.go
+++ b/influxdb.go
@@ -6,8 +6,10 @@ import (
 	client "github.com/influxdata/influxdb/client/v2"
 )
 
+// Point is a datapoint to be logged in to InfluxDB.
 type Point = *client.Point
 
+// NewPoint is a convenience function to create a new Point.
 func NewPoint(name string, tags map[string]string, fields map[string]interface{}) Point {
 	pt, err := client.NewPoint(name, tags, fields, time.Now())
 	if err != nil {
diff --git a/jwg.go b/jwg.go
index a7fd343..5b4f8a8 100644
--- a/jwg.go
+++ b/jwg.go
@@ -7,12 +7,15 @@ import (
 	"time"
 )
 
+// JobWaitGroup is like sync.WaitGroup, but keeps track of job status,
+// and tracks how long each job took.
 type JobWaitGroup struct {
 	lock sync.RWMutex
 	jobs map[string]time.Duration
 	wg   sync.WaitGroup
 }
 
+// Do a job.
 func (jwg *JobWaitGroup) Do(name string, fn func()) {
 	jwg.lock.Lock()
 	defer jwg.lock.Unlock()
@@ -37,11 +40,14 @@ func (jwg *JobWaitGroup) Do(name string, fn func()) {
 	}()
 }
 
+// Wait for all jobs to finish, and return how long each job took.
 func (jwg *JobWaitGroup) Wait() map[string]time.Duration {
 	jwg.wg.Wait()
 	return jwg.jobs
 }
 
+// Status returns the total number of jobs that have been started, and
+// a list of still-running jobs.
 func (jwg *JobWaitGroup) Status() (int, []string) {
 	jwg.lock.RLock()
 
diff --git a/main.go b/main.go
index a89dc46..9c86758 100644
--- a/main.go
+++ b/main.go
@@ -12,6 +12,8 @@ import (
 	"time"
 )
 
+// Given a host/node name and a port number, format a string suitable
+// for net.Dial.
 func fmtAddress(node, port string) string {
 	if isIPv6(node) {
 		return fmt.Sprintf("[%s]:%s", node, port)
@@ -27,33 +29,33 @@ func isIPv6(node string) bool {
 
 var jwg JobWaitGroup
 
-func Emit(pt Point) {
+func emit(pt Point) {
 	if pt == nil {
 		return
 	}
 	fmt.Println(pt)
 }
 
-func DoHostfile(fname string) {
+func doHostfile(fname string) {
 	hostname := filepath.Base(fname)
 
-	cfg, err := readConfigFile(fname)
+	cfg, err := ReadConfigFile(fname)
 	if err != nil {
-		Emit(NewPoint("public", map[string]string{"host": hostname}, map[string]interface{}{"error": err.Error()}))
+		emit(NewPoint("public", map[string]string{"host": hostname}, map[string]interface{}{"error": err.Error()}))
 		return
 	}
 
 	addresses := make(map[string]struct{})
-	for _, address := range getAddresses(cfg) {
+	for _, address := range GetAddresses(cfg) {
 		addresses[fmtAddress(address.Node, address.Port)] = struct{}{}
 	}
 	for address := range addresses {
-		jwg.Do(hostname+"/"+address+"/tcp4", func() { Emit(DoAddress(hostname, "tcp4", address)) })
-		jwg.Do(hostname+"/"+address+"/tcp6", func() { Emit(DoAddress(hostname, "tcp6", address)) })
+		jwg.Do(hostname+"/"+address+"/tcp4", func() { emit(doAddress(hostname, "tcp4", address)) })
+		jwg.Do(hostname+"/"+address+"/tcp6", func() { emit(doAddress(hostname, "tcp6", address)) })
 	}
 }
 
-func DoAddress(host, network, address string) Point {
+func doAddress(host, network, address string) Point {
 	tags := map[string]string{
 		"host":    host,
 		"network": network,
@@ -75,7 +77,7 @@ func DoAddress(host, network, address string) Point {
 	var result_error error
 	go func() {
 		defer _wg.Done()
-		result_name, result_version, result_error = Hello(addr)
+		result_name, result_version, result_error = hello(addr)
 	}()
 	var result_ping float64
 	go func() {
@@ -102,7 +104,9 @@ var dialer = net.Dialer{
 	Timeout: 10 * time.Second,
 }
 
-func Hello(addr *net.TCPAddr) (name, version string, err error) {
+// hello opens a TCP connection and waits for a Tinc server to say
+// hello.
+func hello(addr *net.TCPAddr) (name, version string, err error) {
 	conn, err := dialer.Dial(addr.Network(), addr.String())
 	if err != nil {
 		return "", "", err
@@ -121,7 +125,7 @@ func Hello(addr *net.TCPAddr) (name, version string, err error) {
 
 func main() {
 	for _, fname := range os.Args[1:] {
-		DoHostfile(fname)
+		doHostfile(fname)
 	}
 	watch(time.Second)
 }
diff --git a/ping.go b/ping.go
index a41b4ab..ba825e8 100644
--- a/ping.go
+++ b/ping.go
@@ -7,6 +7,9 @@ import (
 	"strings"
 )
 
+// Ping sends one ICMP echo packet to the given IP and times how long
+// it takes to get a response, in milleseconds.  Returns -1 if no
+// response is received.
 func Ping(ip net.IP) float64 {
 	cmd := exec.Command("ping",
 		"-n", // numeric
diff --git a/tinc.go b/tinc.go
index 1bfefc6..d06a6d2 100644
--- a/tinc.go
+++ b/tinc.go
@@ -7,6 +7,7 @@ import (
 	"strings"
 )
 
+// Error is a parse error recording the filename and line number.
 type Error struct {
 	File string
 	Line int
@@ -38,7 +39,10 @@ func parseConfigLine(line string) (key, val string) {
 	return variable, value
 }
 
-func readConfigFile(fname string) (map[string][]string, error) {
+// ReadConfigFile opens and reads a Tinc configuration file, returning
+// a map of settings.  Since Tinc setting names are case-insensitive,
+// the keys in the map are all lower-case.
+func ReadConfigFile(fname string) (map[string][]string, error) {
 	config_tree := make(map[string][]string)
 
 	fp, err := os.Open(fname)
@@ -89,9 +93,9 @@ func readConfigFile(fname string) (map[string][]string, error) {
 	return config_tree, nil
 }
 
-// Returns a list of public addresses for a host-config in Go
-// "net.Dial" format.
-func getAddresses(cfg map[string][]string) []struct{ Node, Port string } {
+// GetAddresses inspects a tinc host-confing settings object and
+// returns a list of public addresses in it.
+func GetAddresses(cfg map[string][]string) []struct{ Node, Port string } {
 	var result []struct{ Node, Port string }
 
 	for _, node := range cfg["address"] {