style(agent): 💡 add function comments

internal/agent/agent.go

@@ -151,16 +151,16 @@ func Run(ctx context.Context) error {
 
 		client.Endpoint(prefs.RestAPIURL(), hass.DefaultTimeout)
 
-		// Get OS sensor and event workers.
+		// Initialize and gather OS sensor and event workers.
 		sensorWorkers, eventWorkers := setupOSWorkers(runCtx)
-		// Add connection latency sensor worker.
+		// Initialize and add connection latency sensor worker.
 		sensorWorkers = append(sensorWorkers, agentsensor.NewConnectionLatencySensorWorker(prefs))
-		// Add external IP address sensor worker.
+		// Initialize and add external IP address sensor worker.
 		sensorWorkers = append(sensorWorkers, agentsensor.NewExternalIPUpdaterWorker(runCtx))
-		// Add external version sensor worker.
+		// Initialize and add external version sensor worker.
 		sensorWorkers = append(sensorWorkers, agentsensor.NewVersionWorker())
 
-		// Get script workers.
+		// Initialize and add the script worker.
 		scriptsWorkers, err := scripts.NewScriptsWorker(runCtx)
 		if err != nil {
 			logging.FromContext(runCtx).Warn("Could not init scripts workers.", slog.Any("error", err))
@@ -266,7 +266,7 @@ func Reset(ctx context.Context) error {
 	}
 
 	if prefs.IsMQTTEnabled() {
-		if err := resetMQTTControllers(ctx, prefs); err != nil {
+		if err := resetMQTTWorkers(ctx, prefs); err != nil {
 			logging.FromContext(ctx).Error("Problems occurred resetting MQTT configuration.", slog.Any("error", err))
 		}
 	}

internal/agent/mqtt.go

@@ -19,7 +19,7 @@ import (
 )
 
 // MQTTWorker represents an object that is responsible for controlling the
-// publishing of one or more commands over MQTT.
+// publishing of data over MQTT.
 type MQTTWorker interface {
 	// Subscriptions is a list of MQTT subscriptions this object wants to
 	// establish on the MQTT broker.
@@ -58,6 +58,8 @@ type mqttEntities struct {
 	cameras       []*mqtthass.CameraEntity
 }
 
+// setupMQTT will create a slice of MQTTWorker from the custom commands
+// configuration and any OS-specific MQTT workers.
 func setupMQTT(ctx context.Context, prefs *preferences.Preferences) []MQTTWorker {
 	var workers []MQTTWorker
 
@@ -123,7 +125,8 @@ func processMQTTWorkers(ctx context.Context, prefs mqttapi.Preferences, controll
 	}
 }
 
-func resetMQTTControllers(ctx context.Context, prefs *preferences.Preferences) error {
+// resetMQTTWorkers will unpublish configs for all defined MQTTWorkers.
+func resetMQTTWorkers(ctx context.Context, prefs *preferences.Preferences) error {
 	var configs []*mqttapi.Msg
 
 	workers := setupMQTT(ctx, prefs)

internal/agent/mqtt_linux.go

@@ -19,6 +19,7 @@ import (
 	"github.com/joshuar/go-hass-agent/internal/logging"
 )
 
+// linuxMQTTWorker represents the Linux-specific OS MQTTWorker.
 type linuxMQTTWorker struct {
 	*mqttEntities
 	logger *slog.Logger

internal/agent/workers.go

@@ -15,21 +15,29 @@ import (
 	"github.com/joshuar/go-hass-agent/internal/logging"
 )
 
+// Worker is the base interface representing a worker that produces sensors or
+// events. It has an ID and functions to start/stop producing sensors/events.
 type Worker[T any] interface {
 	ID() string
 	Stop() error
 	Start(ctx context.Context) (<-chan T, error)
 }
 
+// SensorWorker is a worker that produces sensors. In addition to the base
+// worker methods, it has a function to generate a list of sensor values.
 type SensorWorker interface {
 	Worker[sensor.Entity]
 	Sensors(ctx context.Context) ([]sensor.Entity, error)
 }
 
+// EventWorker is a worker that produces events. It does not extend further from
+// the base worker other than defining the type of data produced.
 type EventWorker interface {
 	Worker[event.Event]
 }
 
+// startWorkers takes a slice of Workers of a particular type (sensor or event)
+// and runs their start functions, logging any errors.
 func startWorkers[T any](ctx context.Context, workers ...Worker[T]) []<-chan T {
 	var eventCh []<-chan T
 
@@ -51,6 +59,8 @@ func startWorkers[T any](ctx context.Context, workers ...Worker[T]) []<-chan T {
 	return eventCh
 }
 
+// stopWorkers takes a slice of Workers of a particular type (sensor or event)
+// and runs their stop functions, logging any errors.
 func stopWorkers[T any](ctx context.Context, workers ...Worker[T]) {
 	for _, worker := range workers {
 		logging.FromContext(ctx).Debug("Stopping worker", slog.String("worker", worker.ID()))
@@ -64,6 +74,9 @@ func stopWorkers[T any](ctx context.Context, workers ...Worker[T]) {
 	}
 }
 
+// processWorkers handles starting, stopping and processing data from a slice of
+// workers passed in.  It will start the workers, monitor for data and send it
+// to Home Assistant, and stop workers when the passed context is canceled.
 func processWorkers[T any](ctx context.Context, hassclient *hass.Client, workers ...Worker[T]) {
 	// Start all inactive workers of all controllers.
 	workerOutputs := startWorkers(ctx, workers...)

internal/agent/workers_linux.go

@@ -64,10 +64,14 @@ var sensorLaptopWorkersInitFuncs = []func(ctx context.Context) (*linux.EventSens
 	power.NewLaptopWorker, location.NewLocationWorker,
 }
 
+// eventWorkersInitFuncs are event workers that produce events rather than sensors.
 var eventWorkersInitFuncs = []func(ctx context.Context) (*linux.EventWorker, error){
 	system.NewUserSessionEventsWorker,
 }
 
+// setupOSWorkers creates slices of OS-specific sensor and event Workers that
+// can be run by the agent. It handles initializing the workers with OS-specific
+// data, reporting any errors.
 func setupOSWorkers(ctx context.Context) ([]Worker[sensor.Entity], []Worker[event.Event]) {
 	eventWorkers := make([]Worker[event.Event], 0, len(eventWorkersInitFuncs))
 	sensorWorkers := make([]Worker[sensor.Entity], 0,