docs: document packages, exported API and non-obvious logic

internal/config/config.go

@@ -1,3 +1,8 @@
+// Package config resolves where godeez reads its session from and writes its
+// downloads to. There is no config file: the output directory is fixed and
+// the only setting is the DEEZER_ARL environment variable, which exists as an
+// escape hatch for users who would rather not store credentials in the system
+// keyring.
 package config
 
 import (
@@ -13,6 +18,12 @@ type Config struct {
 	OutputDir string
 }
 
+// Load resolves the configuration and creates the output directory.
+//
+// An empty ARLCookie is normal and not an error: it means fall back to the
+// stored credentials, which is the usual path. Creating the directory here
+// rather than at first write means a bad path fails immediately instead of
+// after the first track has been fetched.
 func Load() (*Config, error) {
 	arl := os.Getenv("DEEZER_ARL")
 

internal/config/migrate.go

@@ -6,6 +6,17 @@ import (
 	"path/filepath"
 )
 
+// MigrateLegacy moves the download ledger from the old ~/.godeez directory
+// next to the user's music, where it now lives.
+//
+// It is silent and best effort throughout. A failed migration costs the user
+// their skip history, which the next download simply rebuilds, so there is
+// nothing worth interrupting them about. An existing database at the new
+// location always wins, which makes this safe to run on every download rather
+// than needing a flag to say whether it has happened yet.
+//
+// The rename is attempted first and falls back to a copy, because the old and
+// new locations are often on different filesystems.
 func MigrateLegacy(outputDir string) {
 	homeDir, err := os.UserHomeDir()
 	if err != nil {