Add comprehensive godoc documentation to all exported symbols

- Document all exported types, functions, methods, and constants across 52 files
- Add package-level doc comments to client, models, utils, and ynison packages
- Document HTTP method and endpoint path for each API client method
- Document model struct fields and DeJSON/DeList/ToJSON/ToMap methods
- Fix duplicate package doc comment in internal/models/base.go

Co-Authored-By: Claude Code <noreply@anthropic.com>

internal/client/playlists.go

@@ -1,3 +1,4 @@
+// Package client provides methods for interacting with Yandex Music API endpoints.
 package client
 
 import (
@@ -8,7 +9,8 @@ import (
 	"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/utils"
 )
 
-// GetPlaylists gets playlists by IDs (kinds)
+// GetPlaylists gets playlists by their kind IDs (GET /playlists).
+// Returns a slice of Playlist pointers, or nil if no kinds are provided.
 func (c *Client) GetPlaylists(ctx context.Context, kinds []int) ([]*models.Playlist, error) {
 	if len(kinds) == 0 {
 		return nil, nil
@@ -40,7 +42,8 @@ func (c *Client) GetPlaylists(ctx context.Context, kinds []int) ([]*models.Playl
 	return playlists, nil
 }
 
-// GetPlaylist gets a single playlist by kind
+// GetPlaylist gets a single playlist by kind using GetPlaylists.
+// Returns an error if no playlist is found with the given kind.
 func (c *Client) GetPlaylist(ctx context.Context, kind int) (*models.Playlist, error) {
 	playlists, err := c.GetPlaylists(ctx, []int{kind})
 	if err != nil {
@@ -52,8 +55,7 @@ func (c *Client) GetPlaylist(ctx context.Context, kind int) (*models.Playlist, e
 	return playlists[0], nil
 }
 
-// GetUserPlaylists gets playlists for a user
-// GET /users/{userID}/playlists
+// GetUserPlaylists gets playlists for a user (GET /users/{userID}/playlists).
 func (c *Client) GetUserPlaylists(ctx context.Context, userID string) ([]*models.Playlist, error) {
 	var result []models.Playlist
 	if err := c.request.Get(ctx, fmt.Sprintf("/users/%s/playlists", userID), nil, &result); err != nil {
@@ -68,7 +70,8 @@ func (c *Client) GetUserPlaylists(ctx context.Context, userID string) ([]*models
 	return playlists, nil
 }
 
-// CreatePlaylist creates a new playlist
+// CreatePlaylist creates a new playlist (POST /users/me/playlists).
+// The visibility parameter should be "public" or "private".
 func (c *Client) CreatePlaylist(ctx context.Context, title string, visibility string) (*models.Playlist, error) {
 	params := map[string]string{
 		"title":      title,
@@ -83,7 +86,8 @@ func (c *Client) CreatePlaylist(ctx context.Context, title string, visibility st
 	return &result, nil
 }
 
-// EditPlaylist edits an existing playlist
+// EditPlaylist edits an existing playlist (PUT /users/me/playlists).
+// Only non-empty parameters are updated.
 func (c *Client) EditPlaylist(ctx context.Context, kind int, title, description, visibility string) (*models.Playlist, error) {
 	params := map[string]string{
 		"kind": fmt.Sprintf("%d", kind),
@@ -106,7 +110,7 @@ func (c *Client) EditPlaylist(ctx context.Context, kind int, title, description,
 	return &result, nil
 }
 
-// DeletePlaylist deletes a playlist
+// DeletePlaylist deletes a playlist (DELETE /users/me/playlists).
 func (c *Client) DeletePlaylist(ctx context.Context, kind int) error {
 	params := map[string]string{
 		"kind": fmt.Sprintf("%d", kind),
@@ -115,7 +119,8 @@ func (c *Client) DeletePlaylist(ctx context.Context, kind int) error {
 	return c.request.Delete(ctx, "/users/me/playlists", params, &result)
 }
 
-// AddTracksToPlaylist adds tracks to a playlist
+// AddTracksToPlaylist adds tracks to a playlist (POST /users/me/playlists/tracks).
+// The revision parameter is the current playlist revision for optimistic concurrency.
 func (c *Client) AddTracksToPlaylist(ctx context.Context, kind int, trackIDs []string, revision int) (*models.Playlist, error) {
 	if len(trackIDs) == 0 {
 		return nil, utils.NewYandexMusicError("no tracks provided", utils.ErrBadRequest)
@@ -143,7 +148,8 @@ func (c *Client) AddTracksToPlaylist(ctx context.Context, kind int, trackIDs []s
 	return &result, nil
 }
 
-// RemoveTracksFromPlaylist removes tracks from a playlist
+// RemoveTracksFromPlaylist removes tracks from a playlist (DELETE /users/me/playlists/tracks).
+// The revision parameter is the current playlist revision for optimistic concurrency.
 func (c *Client) RemoveTracksFromPlaylist(ctx context.Context, kind int, trackIDs []string, revision int) (*models.Playlist, error) {
 	if len(trackIDs) == 0 {
 		return nil, utils.NewYandexMusicError("no tracks provided", utils.ErrBadRequest)
@@ -171,7 +177,8 @@ func (c *Client) RemoveTracksFromPlaylist(ctx context.Context, kind int, trackID
 	return &result, nil
 }
 
-// ReorderPlaylistTracks reorders tracks in a playlist
+// ReorderPlaylistTracks reorders tracks in a playlist (PUT /users/me/playlists/tracks/reorder).
+// The from and to parameters specify the position range to move.
 func (c *Client) ReorderPlaylistTracks(ctx context.Context, kind int, from, to, revision int) (*models.Playlist, error) {
 	params := map[string]string{
 		"kind":     fmt.Sprintf("%d", kind),
@@ -188,7 +195,7 @@ func (c *Client) ReorderPlaylistTracks(ctx context.Context, kind int, from, to,
 	return &result, nil
 }
 
-// GetPlaylistRecommendations gets playlist recommendations
+// GetPlaylistRecommendations gets playlist recommendations based on a playlist kind (GET /playlists/recommendations).
 func (c *Client) GetPlaylistRecommendations(ctx context.Context, kind int) ([]*models.Playlist, error) {
 	params := map[string]string{
 		"kind": fmt.Sprintf("%d", kind),