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

internal/store/download_info.go

@@ -9,6 +9,10 @@ import (
 	"go.etcd.io/bbolt"
 )
 
+// DownloadInfo records one completed download. Quality is stored so that
+// re-requesting the same track at a higher quality is not mistaken for a
+// duplicate, and Hash lets a file that has since been moved or renamed still
+// be recognised.
 type DownloadInfo struct {
 	TrackID    string    `json:"song_id"`
 	Quality    string    `json:"quality"`
@@ -19,6 +23,9 @@ type DownloadInfo struct {
 
 var trackBucket = []byte("tracks")
 
+// DownloadInfo returns the record for trackID. A track that has never been
+// downloaded is reported as an error rather than a nil result, and callers
+// treat any error the same way: download it.
 func (s *Store) DownloadInfo(trackID string) (*DownloadInfo, error) {
 	var info DownloadInfo
 

internal/store/store.go

@@ -1,3 +1,9 @@
+// Package store keeps the ledger of what has already been downloaded, so a
+// repeated run can skip tracks instead of fetching them again.
+//
+// It is a bbolt database written as a hidden file inside the output
+// directory, which keeps it travelling with the music library it describes.
+// Losing it is harmless: the worst outcome is re-downloading.
 package store
 
 import (
@@ -14,6 +20,11 @@ type Store struct {
 	db *bbolt.DB
 }
 
+// Open opens the ledger in dir, creating it if needed.
+//
+// bbolt takes an exclusive file lock, so a second godeez running against the
+// same output directory blocks here. The timeout turns that into a clear
+// message rather than an apparent hang.
 func Open(dir string) (*Store, error) {
 	db, err := bbolt.Open(filepath.Join(dir, ".tracks.db"), 0600, &bbolt.Options{Timeout: 5 * time.Second})
 	if err != nil {