more docs.

unifipoller/worker.go

@@ -52,7 +52,10 @@ func (u *UnifiPoller) PollController() error {
 }
 
 // CollectAndReport collects measurements and reports them to influxdb.
-// Can be called once or in a ticker loop.
+// Can be called once or in a ticker loop. This function and all the ones below
+// handle their own logging. An error is returned so the calling function may
+// determine if there was a read or write erorr and act on it. This is currently
+// called in two places in this library. One returns an error, one does not.
 func (u *UnifiPoller) CollectAndReport() error {
 	metrics, err := u.CollectMetrics()
 	if err != nil {
@@ -64,7 +67,7 @@ func (u *UnifiPoller) CollectAndReport() error {
 }
 
 // CollectMetrics grabs all the measurements from a UniFi controller and returns them.
-// This also creates an InfluxDB writer, and returns error if that fails.
+// This also creates an InfluxDB writer, and returns an error if that fails.
 func (u *UnifiPoller) CollectMetrics() (*Metrics, error) {
 	m := &Metrics{}
 	var err error
@@ -91,7 +94,7 @@ func (u *UnifiPoller) ReportMetrics(metrics *Metrics) error {
 	}
 	err := u.Write(metrics.BatchPoints)
 	if err != nil {
-		return errors.Wrap(err, "infdb.Write(bp)")
+		return errors.Wrap(err, "influxdb.Write(points)")
 	}
 	var fields, points int
 	for _, p := range metrics.Points() {
@@ -108,6 +111,12 @@ func (u *UnifiPoller) ReportMetrics(metrics *Metrics) error {
 
 // ProcessPoints batches all device and client data into influxdb data points.
 // Call this after you've collected all the data you care about.
+// This function is sorta weird and returns a slice of errors. The reasoning is
+// that some points may process while others fail, so we attempt to process them
+// all. This is (usually) run in a loop, so we can't really exit on error,
+// we just log the errors and tally them on a counter. In reality, this never
+// returns any errors because we control the data going in; cool right? But we
+// still check&log it in case the data going is skewed up and causes errors!
 func (m *Metrics) ProcessPoints() (errs []error) {
 	for _, asset := range m.Sites {
 		errs = append(errs, m.processPoints(asset))