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

internal/deezer/kind.go

@@ -2,6 +2,11 @@ package deezer
 
 import "fmt"
 
+// Kind is the type of Deezer resource being downloaded. It is the single
+// source of truth for the four supported resources: the cmd package derives
+// its download subcommands from these constants, and each kind maps to a
+// gw-light page method, the request field naming its id, and a Resource
+// implementation. Adding a kind means extending all three switches below.
 type Kind string
 
 const (
@@ -26,6 +31,9 @@ func (k Kind) pageMethod() string {
 	return ""
 }
 
+// idKey returns the request field that carries the resource id. The names are
+// Deezer's own internal abbreviations and do not follow from the kind, so they
+// have to be spelled out. A track is a "song" on the wire.
 func (k Kind) idKey() string {
 	switch k {
 	case KindAlbum:
@@ -41,6 +49,9 @@ func (k Kind) idKey() string {
 	return ""
 }
 
+// newResource returns an empty Resource for the kind. KindTrack maps to
+// Single because a single track page has its own response shape rather than
+// being an album with one entry.
 func (k Kind) newResource() (Resource, error) {
 	switch k {
 	case KindAlbum: