Merge pull request #271 from flimzy/godoc

Misc GoDoc updates

album.go

@@ -13,7 +13,7 @@ import (
 type SimpleAlbum struct {
 	// The name of the album.
 	Name string `json:"name"`
-	// A slice of SimpleArtists
+	// A slice of [SimpleArtist].
 	Artists []SimpleArtist `json:"artists"`
 	// The field is present when getting an artist’s
 	// albums. Possible values are “album”, “single”,
@@ -24,15 +24,20 @@ type SimpleAlbum struct {
 	// The type of the album: one of "album",
 	// "single", or "compilation".
 	AlbumType string `json:"album_type"`
-	// The SpotifyID for the album.
+	// The [Spotify ID] for the album.
+	//
+	// [Spotify ID]: https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
 	ID ID `json:"id"`
-	// The SpotifyURI for the album.
+	// The [Spotify URI] for the album.
+	//
+	// [Spotify URI]: https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
 	URI URI `json:"uri"`
-	// The markets in which the album is available,
-	// identified using ISO 3166-1 alpha-2 country
-	// codes.  Note that al album is considered
-	// available in a market when at least 1 of its
-	// tracks is available in that market.
+	// The markets in which the album is available, identified using
+	// [ISO 3166-1 alpha-2] country codes.  Note that an album is considered
+	// available in a market when at least 1 of its tracks is available in that
+	// market.
+	//
+	// [ISO 3166-1 alpha-2]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
 	AvailableMarkets []string `json:"available_markets"`
 	// A link to the Web API endpoint providing full
 	// details of the album.
@@ -44,18 +49,18 @@ type SimpleAlbum struct {
 	ExternalURLs map[string]string `json:"external_urls"`
 	// The date the album was first released.  For example, "1981-12-15".
 	// Depending on the ReleaseDatePrecision, it might be shown as
-	// "1981" or "1981-12". You can use ReleaseDateTime to convert this
-	// to a time.Time value.
+	// "1981" or "1981-12". You can use [SimpleAlbum.ReleaseDateTime] to convert
+	// this to a [time.Time] value.
 	ReleaseDate string `json:"release_date"`
 	// The precision with which ReleaseDate value is known: "year", "month", or "day"
 	ReleaseDatePrecision string `json:"release_date_precision"`
 	// The number of tracks on the album.
 	TotalTracks Numeric `json:"total_tracks"`
 }
 
-// ReleaseDateTime converts the album's ReleaseDate to a time.TimeValue.
+// ReleaseDateTime converts [SimpleAlbum.ReleaseDate] to a [time.Time].
 // All of the fields in the result may not be valid.  For example, if
-// ReleaseDatePrecision is "month", then only the month and year
+// [SimpleAlbum.ReleaseDatePrecision] is "month", then only the month and year
 // (but not the day) of the result are valid.
 func (s *SimpleAlbum) ReleaseDateTime() time.Time {
 	if s.ReleaseDatePrecision == "day" {
@@ -80,7 +85,7 @@ type Copyright struct {
 	Type string `json:"type"`
 }
 
-// FullAlbum provides extra album data in addition to the data provided by SimpleAlbum.
+// FullAlbum provides extra album data in addition to the data provided by [SimpleAlbum].
 type FullAlbum struct {
 	SimpleAlbum
 	Copyrights []Copyright `json:"copyrights"`
@@ -93,18 +98,19 @@ type FullAlbum struct {
 	ExternalIDs map[string]string `json:"external_ids"`
 }
 
-// SavedAlbum provides info about an album saved to an user's account.
+// SavedAlbum provides info about an album saved to a user's account.
 type SavedAlbum struct {
 	// The date and time the track was saved, represented as an ISO
 	// 8601 UTC timestamp with a zero offset (YYYY-MM-DDTHH:MM:SSZ).
-	// You can use the TimestampLayout constant to convert this to
-	// a time.Time value.
+	// You can use [TimestampLayout] to convert this to a [time.Time] value.
 	AddedAt   string `json:"added_at"`
 	FullAlbum `json:"album"`
 }
 
-// GetAlbum gets Spotify catalog information for a single album, given its Spotify ID.
-// Supported options: Market
+// GetAlbum gets Spotify catalog information for a single album, given its
+// [Spotify ID]. Supported options: [Market].
+//
+// [Spotify ID]: https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
 func (c *Client) GetAlbum(ctx context.Context, id ID, opts ...RequestOption) (*FullAlbum, error) {
 	spotifyURL := fmt.Sprintf("%salbums/%s", c.baseURL, id)
 
@@ -130,14 +136,15 @@ func toStringSlice(ids []ID) []string {
 	return result
 }
 
-// GetAlbums gets Spotify Catalog information for multiple albums, given their
-// Spotify IDs.  It supports up to 20 IDs in a single call.  Albums are returned
+// GetAlbums gets Spotify Catalog information for [multiple albums], given their
+// [Spotify ID]s.  It supports up to 20 IDs in a single call.  Albums are returned
 // in the order requested.  If an album is not found, that position in the
 // result slice will be nil.
 //
-// Doc API: https://developer.spotify.com/documentation/web-api/reference/albums/get-several-albums/
+// Supported options: [Market].
 //
-// Supported options: Market
+// [multiple albums]: https://developer.spotify.com/documentation/web-api/reference/get-multiple-albums
+// [Spotify ID]: https://developer.spotify.com/documentation/web-api/concepts/spotify-uris-ids
 func (c *Client) GetAlbums(ctx context.Context, ids []ID, opts ...RequestOption) ([]*FullAlbum, error) {
 	if len(ids) > 20 {
 		return nil, errors.New("spotify: exceeded maximum number of albums")
@@ -190,11 +197,13 @@ func (at AlbumType) encode() string {
 	return strings.Join(types, ",")
 }
 
-// GetAlbumTracks gets the tracks for a particular album.
+// GetAlbumTracks gets the [tracks] for a particular album.
 // If you only care about the tracks, this call is more efficient
-// than GetAlbum.
+// than [GetAlbum].
+//
+// Supported Options: [Market], [Limit], [Offset].
 //
-// Supported Options: Market, Limit, Offset
+// [tracks]: https://developer.spotify.com/documentation/web-api/reference/get-an-albums-tracks
 func (c *Client) GetAlbumTracks(ctx context.Context, id ID, opts ...RequestOption) (*SimpleTrackPage, error) {
 	spotifyURL := fmt.Sprintf("%salbums/%s/tracks", c.baseURL, id)
 

artist.go

@@ -17,7 +17,7 @@ type SimpleArtist struct {
 	ExternalURLs map[string]string `json:"external_urls"`
 }
 
-// FullArtist provides extra artist data in addition to what is provided by SimpleArtist.
+// FullArtist provides extra artist data in addition to what is provided by [SimpleArtist].
 type FullArtist struct {
 	SimpleArtist
 	// The popularity of the artist, expressed as an integer between 0 and 100.
@@ -66,7 +66,9 @@ func (c *Client) GetArtists(ctx context.Context, ids ...ID) ([]*FullArtist, erro
 
 // GetArtistsTopTracks gets Spotify catalog information about an artist's top
 // tracks in a particular country.  It returns a maximum of 10 tracks.  The
-// country is specified as an ISO 3166-1 alpha-2 country code.
+// country is specified as an [ISO 3166-1 alpha-2] country code.
+//
+// [ISO 3166-1 alpha-2]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
 func (c *Client) GetArtistsTopTracks(ctx context.Context, artistID ID, country string) ([]FullTrack, error) {
 	spotifyURL := fmt.Sprintf("%sartists/%s/top-tracks?country=%s", c.baseURL, artistID, country)
 
@@ -108,7 +110,7 @@ func (c *Client) GetRelatedArtists(ctx context.Context, id ID) ([]FullArtist, er
 // If the Market is not specified, Spotify will likely return a lot
 // of duplicates (one for each market in which the album is available
 //
-// Supported options: Market
+// Supported options: [Market].
 func (c *Client) GetArtistAlbums(ctx context.Context, artistID ID, ts []AlbumType, opts ...RequestOption) (*SimpleAlbumPage, error) {
 	spotifyURL := fmt.Sprintf("%sartists/%s/albums", c.baseURL, artistID)
 	// add optional query string if options were specified

audio_analysis.go

@@ -5,9 +5,11 @@ import (
 	"fmt"
 )
 
-// AudioAnalysis contains a detailed audio analysis for a single track
-// identified by its unique Spotify ID. See:
-// https://developer.spotify.com/web-api/get-audio-analysis/
+// AudioAnalysis contains a [detailed audio analysis] for a single track
+// identified by its unique [Spotify ID].
+//
+// [detailed audio analysis]: https://developer.spotify.com/documentation/web-api/reference/get-audio-analysis
+// [Spotify ID]: https://developer.spotify.com/documentation/web-api/#spotify-uris-and-ids
 type AudioAnalysis struct {
 	Bars     []Marker      `json:"bars"`
 	Beats    []Marker      `json:"beats"`
@@ -95,8 +97,10 @@ type AnalysisTrack struct {
 	RhythmVersion           float64 `json:"rhythm_version"`
 }
 
-// GetAudioAnalysis queries the Spotify web API for an audio analysis of a
+// GetAudioAnalysis queries the Spotify web API for an [audio analysis] of a
 // single track.
+//
+// [audio analysis]: https://developer.spotify.com/documentation/web-api/reference/get-audio-analysis
 func (c *Client) GetAudioAnalysis(ctx context.Context, id ID) (*AudioAnalysis, error) {
 	url := fmt.Sprintf("%saudio-analysis/%s", c.baseURL, id)
 

audio_features.go

@@ -37,8 +37,10 @@ type AudioFeatures struct {
 	// intended to represent instrumental tracks, but confidence is higher as the
 	// value approaches 1.0.
 	Instrumentalness float32 `json:"instrumentalness"`
-	// The key the track is in.  Integers map to pitches using standard Pitch Class notation
-	// (https://en.wikipedia.org/wiki/Pitch_class).
+	// The key the track is in.  Integers map to pitches using standard
+	// [Pitch Class] notation.
+	//
+	// [Pitch Class]: https://en.wikipedia.org/wiki/Pitch_class
 	Key Numeric `json:"key"`
 	// Detects the presence of an audience in the recording.  Higher liveness
 	// values represent an increased probability that the track was performed live.
@@ -73,7 +75,9 @@ type AudioFeatures struct {
 	Valence float32 `json:"valence"`
 }
 
-// Key represents a pitch using Pitch Class notation.
+// Key represents a pitch using [Pitch Class] notation.
+//
+// [Pitch Class]: https://en.wikipedia.org/wiki/Pitch_class
 type Key int
 
 const (

category.go

@@ -21,7 +21,7 @@ type Category struct {
 
 // GetCategory gets a single category used to tag items in Spotify.
 //
-// Supported options: Country, Locale
+// Supported options: [Country], [Locale].
 func (c *Client) GetCategory(ctx context.Context, id string, opts ...RequestOption) (Category, error) {
 	cat := Category{}
 	spotifyURL := fmt.Sprintf("%sbrowse/categories/%s", c.baseURL, id)
@@ -38,7 +38,8 @@ func (c *Client) GetCategory(ctx context.Context, id string, opts ...RequestOpti
 }
 
 // GetCategoryPlaylists gets a list of Spotify playlists tagged with a particular category.
-// Supported options: Country, Limit, Offset
+//
+// Supported options: [Country], [Limit], [Offset].
 func (c *Client) GetCategoryPlaylists(ctx context.Context, catID string, opts ...RequestOption) (*SimplePlaylistPage, error) {
 	spotifyURL := fmt.Sprintf("%sbrowse/categories/%s/playlists", c.baseURL, catID)
 	if params := processOptions(opts...).urlParams.Encode(); params != "" {
@@ -59,7 +60,7 @@ func (c *Client) GetCategoryPlaylists(ctx context.Context, catID string, opts ..
 
 // GetCategories gets a list of categories used to tag items in Spotify
 //
-// Supported options: Country, Locale, Limit, Offset
+// Supported options: [Country], [Locale], [Limit], [Offset].
 func (c *Client) GetCategories(ctx context.Context, opts ...RequestOption) (*CategoryPage, error) {
 	spotifyURL := c.baseURL + "browse/categories"
 	if query := processOptions(opts...).urlParams.Encode(); query != "" {

countries.go

@@ -1,8 +1,8 @@
 package spotify
 
-// ISO 3166-1 alpha 2 country codes.
+// [ISO 3166-1 alpha-2] country codes.
 //
-// see: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+// [ISO 3166-1 alpha-2]: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
 const (
 	CountryArgentina          = "AR"
 	CountryAustralia          = "AU"

cursor.go

@@ -30,7 +30,7 @@ type cursorPage struct {
 }
 
 // FullArtistCursorPage is a cursor-based paging object containing
-// a set of FullArtist objects.
+// a set of [FullArtist] objects.
 type FullArtistCursorPage struct {
 	cursorPage
 	Artists []FullArtist `json:"items"`

library.go

@@ -37,31 +37,31 @@ func (c *Client) libraryContains(ctx context.Context, typ string, ids ...ID) ([]
 }
 
 // AddTracksToLibrary saves one or more tracks to the current user's
-// "Your Music" library.  This call requires the ScopeUserLibraryModify scope.
+// "Your Music" library.  This call requires the [ScopeUserLibraryModify] scope.
 // A track can only be saved once; duplicate IDs are ignored.
 func (c *Client) AddTracksToLibrary(ctx context.Context, ids ...ID) error {
 	return c.modifyLibrary(ctx, "tracks", true, ids...)
 }
 
 // RemoveTracksFromLibrary removes one or more tracks from the current user's
-// "Your Music" library.  This call requires the ScopeUserModifyLibrary scope.
+// "Your Music" library.  This call requires the [ScopeUserModifyLibrary] scope.
 // Trying to remove a track when you do not have the user's authorization
-// results in a `spotify.Error` with the status code set to http.StatusUnauthorized.
+// results in an [Error] with the status code set to [net/http.StatusUnauthorized].
 func (c *Client) RemoveTracksFromLibrary(ctx context.Context, ids ...ID) error {
 	return c.modifyLibrary(ctx, "tracks", false, ids...)
 }
 
 // AddAlbumsToLibrary saves one or more albums to the current user's
-// "Your Albums" library.  This call requires the ScopeUserLibraryModify scope.
+// "Your Albums" library.  This call requires the [ScopeUserLibraryModify] scope.
 // A track can only be saved once; duplicate IDs are ignored.
 func (c *Client) AddAlbumsToLibrary(ctx context.Context, ids ...ID) error {
 	return c.modifyLibrary(ctx, "albums", true, ids...)
 }
 
 // RemoveAlbumsFromLibrary removes one or more albums from the current user's
-// "Your Albums" library.  This call requires the ScopeUserModifyLibrary scope.
+// "Your Albums" library.  This call requires the [ScopeUserModifyLibrary] scope.
 // Trying to remove a track when you do not have the user's authorization
-// results in a `spotify.Error` with the status code set to http.StatusUnauthorized.
+// results in an [Error] with the status code set to [net/http.StatusUnauthorized].
 func (c *Client) RemoveAlbumsFromLibrary(ctx context.Context, ids ...ID) error {
 	return c.modifyLibrary(ctx, "albums", false, ids...)
 }

page.go

@@ -35,49 +35,49 @@ type basePage struct {
 	Previous string `json:"previous"`
 }
 
-// FullArtistPage contains FullArtists returned by the Web API.
+// FullArtistPage contains [FullArtists] returned by the Web API.
 type FullArtistPage struct {
 	basePage
 	Artists []FullArtist `json:"items"`
 }
 
-// SimpleAlbumPage contains SimpleAlbums returned by the Web API.
+// SimpleAlbumPage contains [SimpleAlbums] returned by the Web API.
 type SimpleAlbumPage struct {
 	basePage
 	Albums []SimpleAlbum `json:"items"`
 }
 
-// SavedAlbumPage contains SavedAlbums returned by the Web API.
+// SavedAlbumPage contains [SavedAlbums] returned by the Web API.
 type SavedAlbumPage struct {
 	basePage
 	Albums []SavedAlbum `json:"items"`
 }
 
-// SavedShowPage contains SavedShows returned by the Web API
+// SavedShowPage contains [SavedShows] returned by the Web API
 type SavedShowPage struct {
 	basePage
 	Shows []SavedShow `json:"items"`
 }
 
-// SimplePlaylistPage contains SimplePlaylists returned by the Web API.
+// SimplePlaylistPage contains [SimplePlaylists] returned by the Web API.
 type SimplePlaylistPage struct {
 	basePage
 	Playlists []SimplePlaylist `json:"items"`
 }
 
-// SimpleTrackPage contains SimpleTracks returned by the Web API.
+// SimpleTrackPage contains [SimpleTracks] returned by the Web API.
 type SimpleTrackPage struct {
 	basePage
 	Tracks []SimpleTrack `json:"items"`
 }
 
-// FullTrackPage contains FullTracks returned by the Web API.
+// FullTrackPage contains [FullTracks] returned by the Web API.
 type FullTrackPage struct {
 	basePage
 	Tracks []FullTrack `json:"items"`
 }
 
-// SavedTrackPage contains SavedTracks return by the Web API.
+// SavedTrackPage contains [SavedTracks] return by the Web API.
 type SavedTrackPage struct {
 	basePage
 	Tracks []SavedTrack `json:"items"`
@@ -89,19 +89,19 @@ type PlaylistTrackPage struct {
 	Tracks []PlaylistTrack `json:"items"`
 }
 
-// CategoryPage contains Category objects returned by the Web API.
+// CategoryPage contains [Category] objects returned by the Web API.
 type CategoryPage struct {
 	basePage
 	Categories []Category `json:"items"`
 }
 
-// SimpleEpisodePage contains EpisodePage returned by the Web API.
+// SimpleEpisodePage contains [EpisodePage] returned by the Web API.
 type SimpleEpisodePage struct {
 	basePage
 	Episodes []EpisodePage `json:"items"`
 }
 
-// SimpleShowPage contains ShowPage returned by the Web API.
+// SimpleShowPage contains [ShowPage] returned by the Web API.
 type SimpleShowPage struct {
 	basePage
 	Shows []FullShow `json:"items"`
@@ -114,7 +114,7 @@ type pageable interface{ canPage() }
 func (b *basePage) canPage() {}
 
 // NextPage fetches the next page of items and writes them into p.
-// It returns ErrNoMorePages if p already contains the last page.
+// It returns [ErrNoMorePages] if p already contains the last page.
 func (c *Client) NextPage(ctx context.Context, p pageable) error {
 	if p == nil || reflect.ValueOf(p).IsNil() {
 		return fmt.Errorf("spotify: p must be a non-nil pointer to a page")
@@ -138,7 +138,7 @@ func (c *Client) NextPage(ctx context.Context, p pageable) error {
 }
 
 // PreviousPage fetches the previous page of items and writes them into p.
-// It returns ErrNoMorePages if p already contains the last page.
+// It returns [ErrNoMorePages] if p already contains the last page.
 func (c *Client) PreviousPage(ctx context.Context, p pageable) error {
 	if p == nil || reflect.ValueOf(p).IsNil() {
 		return fmt.Errorf("spotify: p must be a non-nil pointer to a page")