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/ynison/client.go

@@ -1,5 +1,4 @@
-// Package ynison provides a WebSocket client for the Yandex Music Ynison protocol,
-// enabling real-time player synchronization across devices.
+// Package ynison provides a Ynison WebSocket client for player synchronization across devices.
 package ynison
 
 import (
@@ -14,7 +13,7 @@ import (
 	"github.com/gorilla/websocket"
 )
 
-// YnisonClient represents a Ynison WebSocket client
+// YnisonClient represents a Ynison WebSocket client for player synchronization across devices.
 type YnisonClient struct {
 	client      *client.Client
 	conn        *websocket.Conn
@@ -30,7 +29,7 @@ type YnisonClient struct {
 	closeOnce   sync.Once // Ensures doneCh is closed only once
 }
 
-// DeviceConfig holds device configuration for Ynison
+// DeviceConfig holds device configuration for Ynison WebSocket connections.
 type DeviceConfig struct {
 	DeviceID    string
 	Title       string
@@ -42,7 +41,8 @@ type DeviceConfig struct {
 	VolumeGran  int
 }
 
-// NewYnisonClient creates a new Ynison client
+// NewYnisonClient creates a new Ynison client with the given client and device config.
+// Default values are applied for empty fields.
 func NewYnisonClient(c *client.Client, config DeviceConfig) *YnisonClient {
 	if config.DeviceID == "" {
 		config.DeviceID = fmt.Sprintf("go-ynison-%d", time.Now().UnixNano())
@@ -69,7 +69,8 @@ func NewYnisonClient(c *client.Client, config DeviceConfig) *YnisonClient {
 	}
 }
 
-// Connect establishes a WebSocket connection to Ynison
+// Connect establishes a WebSocket connection to the Ynison service.
+// It sends an initial full state update after connecting.
 func (y *YnisonClient) Connect(ctx context.Context) error {
 	token := y.client.GetToken()
 	if token == "" {
@@ -97,12 +98,12 @@ func (y *YnisonClient) Connect(ctx context.Context) error {
 	return y.sendUpdateFullState(ctx)
 }
 
-// overrideWSURL sets a custom WebSocket URL for testing
+// overrideWSURL sets a custom WebSocket URL for testing purposes.
 func (y *YnisonClient) overrideWSURL(url string) {
 	y.wsURL = url
 }
 
-// Disconnect closes the WebSocket connection
+// Disconnect closes the WebSocket connection and cleans up resources.
 func (y *YnisonClient) Disconnect() error {
 	y.mu.Lock()
 	defer y.mu.Unlock()
@@ -119,7 +120,7 @@ func (y *YnisonClient) Disconnect() error {
 	return nil
 }
 
-// IsConnected returns true if the client is connected
+// IsConnected returns true if the client is currently connected to the Ynison service.
 func (y *YnisonClient) IsConnected() bool {
 	y.mu.Lock()
 	defer y.mu.Unlock()
@@ -278,21 +279,22 @@ func (y *YnisonClient) sendRequest(ctx context.Context, req *proto.PutYnisonStat
 	return y.conn.WriteMessage(websocket.TextMessage, data)
 }
 
-// RegisterHandler registers a response handler
+// RegisterHandler registers a response handler for the given name.
+// Handlers are invoked when a PutYnisonStateResponse is received from the server.
 func (y *YnisonClient) RegisterHandler(name string, handler func(*proto.PutYnisonStateResponse)) {
 	y.mu.Lock()
 	defer y.mu.Unlock()
 	y.handlers[name] = handler
 }
 
-// UnregisterHandler removes a response handler
+// UnregisterHandler removes a previously registered response handler by name.
 func (y *YnisonClient) UnregisterHandler(name string) {
 	y.mu.Lock()
 	defer y.mu.Unlock()
 	delete(y.handlers, name)
 }
 
-// UpdatePlayingStatus updates the playing status
+// UpdatePlayingStatus updates the playing status on the Ynison server.
 func (y *YnisonClient) UpdatePlayingStatus(ctx context.Context, status *proto.PlayingStatus) error {
 	req := &proto.PutYnisonStateRequest{
 		UpdatePlayingStatus: &proto.UpdatePlayingStatus{
@@ -304,7 +306,7 @@ func (y *YnisonClient) UpdatePlayingStatus(ctx context.Context, status *proto.Pl
 	return y.sendRequest(ctx, req)
 }
 
-// UpdateVolume updates the volume
+// UpdateVolume updates the volume for a device on the Ynison server.
 func (y *YnisonClient) UpdateVolume(ctx context.Context, deviceID string, volume float64, version *proto.UpdateVersion) error {
 	req := &proto.PutYnisonStateRequest{
 		UpdateVolumeInfo: &proto.UpdateVolumeInfo{
@@ -320,7 +322,7 @@ func (y *YnisonClient) UpdateVolume(ctx context.Context, deviceID string, volume
 	return y.sendRequest(ctx, req)
 }
 
-// UpdateActiveDevice updates the active device
+// UpdateActiveDevice updates the active device on the Ynison server.
 func (y *YnisonClient) UpdateActiveDevice(ctx context.Context, deviceID string) error {
 	req := &proto.PutYnisonStateRequest{
 		UpdateActiveDevice: &proto.UpdateActiveDevice{
@@ -332,7 +334,7 @@ func (y *YnisonClient) UpdateActiveDevice(ctx context.Context, deviceID string)
 	return y.sendRequest(ctx, req)
 }
 
-// UpdatePlayerState updates the player state (queue, repeat, shuffle)
+// UpdatePlayerState updates the player state (queue, repeat, shuffle) on the Ynison server.
 func (y *YnisonClient) UpdatePlayerState(ctx context.Context, state *proto.PlayerState) error {
 	req := &proto.PutYnisonStateRequest{
 		UpdatePlayerState: &proto.UpdatePlayerState{
@@ -344,7 +346,7 @@ func (y *YnisonClient) UpdatePlayerState(ctx context.Context, state *proto.Playe
 	return y.sendRequest(ctx, req)
 }
 
-// UpdatePlayerQueueInject updates the injected queue entity
+// UpdatePlayerQueueInject updates the injected queue entity on the Ynison server.
 func (y *YnisonClient) UpdatePlayerQueueInject(ctx context.Context, inject *proto.PlayerQueueInject) error {
 	req := &proto.PutYnisonStateRequest{
 		UpdatePlayerQueueInject: &proto.UpdatePlayerQueueInject{
@@ -356,7 +358,7 @@ func (y *YnisonClient) UpdatePlayerQueueInject(ctx context.Context, inject *prot
 	return y.sendRequest(ctx, req)
 }
 
-// SyncStateFromEOV requests synchronization from EOV
+// SyncStateFromEOV requests synchronization from EOV (End of Verification).
 func (y *YnisonClient) SyncStateFromEOV(ctx context.Context, actualQueueID string) error {
 	req := &proto.PutYnisonStateRequest{
 		SyncStateFromEov: &proto.SyncStateFromEOV{
@@ -368,25 +370,25 @@ func (y *YnisonClient) SyncStateFromEOV(ctx context.Context, actualQueueID strin
 	return y.sendRequest(ctx, req)
 }
 
-// GetDevices returns the list of connected devices from the last response
+// GetDevices returns the list of connected devices from the last response.
 func (y *YnisonClient) GetDevices() []*proto.Device {
 	// This would need to be implemented with proper state tracking
 	return nil
 }
 
-// GetActiveDeviceID returns the active device ID from the last response
+// GetActiveDeviceID returns the active device ID from the last response.
 func (y *YnisonClient) GetActiveDeviceID() string {
 	// This would need to be implemented with proper state tracking
 	return ""
 }
 
-// GetPlayerState returns the current player state from the last response
+// GetPlayerState returns the current player state from the last response.
 func (y *YnisonClient) GetPlayerState() *proto.PlayerState {
 	// This would need to be implemented with proper state tracking
 	return nil
 }
 
-// WaitForConnection waits for the connection to be established or context to be done
+// WaitForConnection waits for the connection to be established or the context to be done.
 func (y *YnisonClient) WaitForConnection(ctx context.Context) error {
 	select {
 	case <-ctx.Done():

internal/ynison/helpers.go

@@ -1,3 +1,4 @@
+// Package ynison provides a Ynison WebSocket client for player synchronization.
 package ynison
 
 import (
@@ -6,7 +7,8 @@ import (
 	"gitea.mrixs.me/Mrixs/yandex-music-api-go/internal/ynison/proto"
 )
 
-// CreatePlayingStatus creates a playing status
+// CreatePlayingStatus creates a playing status with the given parameters.
+// The version timestamp is set to the current time.
 func CreatePlayingStatus(progressMs, durationMs int64, paused bool, playbackSpeed float64, deviceID string) *proto.PlayingStatus {
 	return &proto.PlayingStatus{
 		ProgressMs:    progressMs,
@@ -21,7 +23,7 @@ func CreatePlayingStatus(progressMs, durationMs int64, paused bool, playbackSpee
 	}
 }
 
-// CreatePlayable creates a playable entity
+// CreatePlayable creates a playable entity with the given parameters.
 func CreatePlayable(playableID, albumID, from, title, coverURL string, playableType proto.PlayablePlayableType) *proto.Playable {
 	return &proto.Playable{
 		PlayableId:       playableID,
@@ -33,7 +35,7 @@ func CreatePlayable(playableID, albumID, from, title, coverURL string, playableT
 	}
 }
 
-// CreateTrackPlayable creates a track playable
+// CreateTrackPlayable creates a track playable with the given parameters.
 func CreateTrackPlayable(playableID, albumID, from, title, coverURL string, trackSourceKey uint32, batchID string) *proto.Playable {
 	return &proto.Playable{
 		PlayableId:       playableID,
@@ -49,7 +51,7 @@ func CreateTrackPlayable(playableID, albumID, from, title, coverURL string, trac
 	}
 }
 
-// CreateVideoClipPlayable creates a video clip playable
+// CreateVideoClipPlayable creates a video clip playable with the given parameters.
 func CreateVideoClipPlayable(playableID, from, title, coverURL string, recommendationType proto.VideoClipInfoRecommendationType) *proto.Playable {
 	return &proto.Playable{
 		PlayableId:       playableID,
@@ -63,7 +65,7 @@ func CreateVideoClipPlayable(playableID, from, title, coverURL string, recommend
 	}
 }
 
-// CreatePlayerQueue creates a player queue
+// CreatePlayerQueue creates a player queue with the given parameters.
 func CreatePlayerQueue(entityID string, entityType proto.PlayerQueueEntityType, playables []*proto.Playable, currentIndex int32, deviceID string) *proto.PlayerQueue {
 	return &proto.PlayerQueue{
 		EntityId:             entityID,
@@ -82,7 +84,7 @@ func CreatePlayerQueue(entityID string, entityType proto.PlayerQueueEntityType,
 	}
 }
 
-// CreateWaveQueue creates a wave queue
+// CreateWaveQueue creates a wave queue with the given parameters.
 func CreateWaveQueue(recommended []*proto.Playable, liveIndex int32, sessionID string, deviceID string) *proto.PlayerQueueQueue {
 	// Build track sources from playables
 	var trackSources []*proto.PlayerQueueQueueWaveQueueEntityOptionsTrackSourceWithKey
@@ -111,7 +113,7 @@ func CreateWaveQueue(recommended []*proto.Playable, liveIndex int32, sessionID s
 	}
 }
 
-// CreateGenerativeQueue creates a generative queue
+// CreateGenerativeQueue creates a generative queue with the given ID.
 func CreateGenerativeQueue(id string) *proto.PlayerQueueQueue {
 	return &proto.PlayerQueueQueue{
 		GenerativeQueue: &proto.PlayerQueueQueueGenerativeQueue{