style(preferences): 💡 add more comments

internal/preferences/context.go

@@ -14,12 +14,14 @@ const (
 	restAPIURLContextKey contextKey = "restAPIURL"
 )
 
+// AppIDToContext will store the given App ID in the context.
 func AppIDToContext(ctx context.Context, appID string) context.Context {
 	newCtx := context.WithValue(ctx, appIDContextKey, appID)
 
 	return newCtx
 }
 
+// AppIDFromContext retrieves the App ID from the context.
 func AppIDFromContext(ctx context.Context) string {
 	appID, ok := ctx.Value(appIDContextKey).(string)
 	if !ok {
@@ -29,12 +31,14 @@ func AppIDFromContext(ctx context.Context) string {
 	return appID
 }
 
+// RestAPIURLToContext will store the given rest API URL in the context.
 func RestAPIURLToContext(ctx context.Context, url string) context.Context {
 	newCtx := context.WithValue(ctx, restAPIURLContextKey, url)
 
 	return newCtx
 }
 
+// RestAPIURLFromContext will retrieve the rest API URL from the context.
 func RestAPIURLFromContext(ctx context.Context) string {
 	url, ok := ctx.Value(appIDContextKey).(string)
 	if !ok {

internal/preferences/device.go

@@ -10,6 +10,7 @@ import (
 	"fmt"
 )
 
+// Device contains the device-specific preferences.
 type Device struct {
 	ID   string `toml:"id" validate:"required,ascii"`
 	Name string `toml:"name" validate:"required,ascii"`

internal/preferences/hass.go

@@ -17,6 +17,7 @@ const (
 	WebHookPath   = "/api/webhook/"
 )
 
+// Hass contains preferences related to connectivity to Home Assistant.
 type Hass struct {
 	CloudhookURL string `toml:"cloudhook_url,omitempty" json:"cloudhook_url" validate:"omitempty,http_url"`
 	RemoteUIURL  string `toml:"remote_ui_url,omitempty" json:"remote_ui_url" validate:"omitempty,http_url"`
@@ -31,6 +32,8 @@ var (
 	ErrSetHassPreference   = errors.New("could not set hass preference")
 )
 
+// SetHassPreferences will set the Hass preferences to the given values.
+//
 //revive:disable:indent-error-flow
 func SetHassPreferences(hassPrefs *Hass, regPrefs *Registration) error {
 	if err := prefsSrc.Set("hass.secret", hassPrefs.Secret); err != nil {

internal/preferences/mqtt.go

@@ -13,6 +13,7 @@ import (
 	"github.com/knadh/koanf/v2"
 )
 
+// MQTT contains preferences related to MQTT functionality in Go Hass Agent.
 type MQTT struct {
 	MQTTServer      string `toml:"server,omitempty" validate:"omitempty,uri" kong:"required,help='MQTT server URI. Required.',placeholder='scheme://some.host:port'"` //nolint:lll
 	MQTTUser        string `toml:"user,omitempty" validate:"omitempty" kong:"optional,help='MQTT username.'"`
@@ -23,6 +24,8 @@ type MQTT struct {
 
 var ErrSetMQTTPreference = errors.New("could not set MQTT preference")
 
+// SetMQTTPreferences will set Go Hass Agent's MQTT preferences to the given
+// values.
 func SetMQTTPreferences(prefs *MQTT) error {
 	if err := prefsSrc.Set("mqtt.server", prefs.MQTTServer); err != nil {
 		return fmt.Errorf("%w: %w", ErrSetMQTTPreference, err)
@@ -47,6 +50,7 @@ func SetMQTTPreferences(prefs *MQTT) error {
 	return nil
 }
 
+// GetMQTTPreferences retrieves the current MQTT preferences from file.
 func GetMQTTPreferences() (*MQTT, error) {
 	var mqttPrefs MQTT
 	// Unmarshal config, overwriting defaults.
@@ -57,6 +61,7 @@ func GetMQTTPreferences() (*MQTT, error) {
 	return &mqttPrefs, nil
 }
 
+// MQTTEnabled will return whether Go Hass Agent will use MQTT.
 func MQTTEnabled() bool {
 	return prefsSrc.Bool("mqtt.enabled")
 }
@@ -98,7 +103,7 @@ func MQTTOrigin() *mqtthass.Origin {
 
 // IsMQTTEnabled is a conveinience function to determine whether MQTT
 // functionality has been enabled in the agent.
-func (p *Preferences) IsMQTTEnabled() bool {
+func (p *preferences) IsMQTTEnabled() bool {
 	if p.MQTT != nil {
 		return p.MQTT.MQTTEnabled
 	}

internal/preferences/prefs.go

@@ -54,7 +54,7 @@ var (
 )
 
 // Default agent preferences.
-var defaultAgentPreferences = &Preferences{
+var defaultAgentPreferences = &preferences{
 	Version:    AppVersion,
 	Registered: false,
 	MQTT: &MQTT{
@@ -78,8 +78,8 @@ var (
 	mu              = sync.Mutex{}
 )
 
-//nolint:tagalign
-type Preferences struct {
+// preferences defines all preferences for Go Hass Agent.
+type preferences struct {
 	MQTT         *MQTT         `toml:"mqtt,omitempty"`
 	Registration *Registration `toml:"registration"`
 	Hass         *Hass         `toml:"hass"`
@@ -139,7 +139,7 @@ func Reset(ctx context.Context) error {
 
 // Validate ensures the configuration is valid.
 func Validate() error {
-	currentPreferences := &Preferences{}
+	currentPreferences := &preferences{}
 
 	// Unmarshal current preferences.
 	if err := prefsSrc.UnmarshalWithConf("", currentPreferences, koanf.UnmarshalConf{Tag: "toml"}); err != nil {
@@ -203,6 +203,8 @@ func Registered() bool {
 	return prefsSrc.Bool("registered")
 }
 
+// checkPath checks that the given directory exists. If it doesn't it will be
+// created.
 func checkPath(path string) error {
 	_, err := os.Stat(path)
 	if os.IsNotExist(err) {

internal/preferences/registration.go

@@ -11,6 +11,8 @@ import (
 	"github.com/joshuar/go-hass-agent/internal/validation"
 )
 
+// Registration are the preferences that defines how Go Hass Agent registers
+// with Home Assistant.
 type Registration struct {
 	Server         string `toml:"server" validate:"required,http_url"`
 	Token          string `toml:"token" validate:"required"`
@@ -26,10 +28,13 @@ func (p *Registration) Validate() error {
 	return nil
 }
 
-func (p *Preferences) Server() string {
+// Server returns the server that was used for registering Go Hass Agent.
+func (p *preferences) Server() string {
 	return p.Registration.Server
 }
 
-func (p *Preferences) Token() string {
+// Token returns the long-lived access token that was used by Go Hass Agent for
+// registering with Home Assistant.
+func (p *preferences) Token() string {
 	return p.Registration.Token
 }

internal/preferences/worker.go

@@ -21,7 +21,7 @@ type CommonWorkerPrefs struct {
 // Worker represents a Worker from the point of the preferences package. A
 // worker has a set of default preferences returned by the DefaultPreferences
 // method and an ID that uniquely identifies the worker (and its preferences
-// file on disk).
+// on disk).
 type Worker[T any] interface {
 	PreferencesID() string
 	DefaultPreferences() T
@@ -32,6 +32,7 @@ var (
 	ErrLoadWorkerPrefs = errors.New("error loading worker preferences")
 )
 
+// LoadWorker reads the given worker's preferences from file.
 func LoadWorker[T any](ctx context.Context, worker Worker[T]) (*T, error) {
 	// Load default worker prefs.
 	var prefs T
@@ -64,6 +65,7 @@ func LoadWorker[T any](ctx context.Context, worker Worker[T]) (*T, error) {
 	return &prefs, nil
 }
 
+// SaveWorker saves the given worker's preferences to file.
 func SaveWorker[T any](ctx context.Context, worker Worker[T], prefs T) error {
 	// We can't define the structure for every possible worker beforehand, so
 	// use map[string]any as the structure for saving.