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/utils/schema.go

@@ -9,16 +9,24 @@ import (
 	"sync"
 )
 
-// SchemaMismatch represents a mismatch between expected and actual API response
+// SchemaMismatch represents a mismatch between expected and actual API response.
+// It captures details about missing fields, unknown fields, and unknown values.
 type SchemaMismatch struct {
-	ModelName      string
-	MissingFields  []string
-	UnknownFields  []string
-	UnknownValues  map[string]any
-	Endpoint       string
+	// ModelName is the name of the model that had the mismatch.
+	ModelName string
+	// MissingFields lists fields that were expected but not found in the response.
+	MissingFields []string
+	// UnknownFields lists fields that were not expected but found in the response.
+	UnknownFields []string
+	// UnknownValues maps unknown field names to their values.
+	UnknownValues map[string]any
+	// Endpoint is the API endpoint where the mismatch occurred.
+	Endpoint string
+	// LibraryVersion is the version of the library when the mismatch occurred.
 	LibraryVersion string
 }
 
+// Describe returns a human-readable description of the schema mismatch.
 func (sm *SchemaMismatch) Describe() string {
 	var parts []string
 	parts = append(parts, fmt.Sprintf("Model: %s", sm.ModelName))
@@ -36,17 +44,22 @@ func (sm *SchemaMismatch) Describe() string {
 	return strings.Join(parts, "\n")
 }
 
-// SchemaMismatchHandler is a callback for handling schema mismatches
+// SchemaMismatchHandler is a callback for handling schema mismatches.
+// It is invoked when a schema mismatch is detected, if configured.
 type SchemaMismatchHandler func(*SchemaMismatch)
 
-// SchemaMismatchConfig holds configuration for schema mismatch handling
+// SchemaMismatchConfig holds configuration for schema mismatch handling.
 type SchemaMismatchConfig struct {
+	// ReportUnknownFields indicates whether unknown fields should be reported.
 	ReportUnknownFields bool
-	Strict              bool
-	OnSchemaMismatch    SchemaMismatchHandler
+	// Strict indicates whether schema mismatches should be treated as errors.
+	Strict bool
+	// OnSchemaMismatch is an optional callback for custom mismatch handling.
+	OnSchemaMismatch SchemaMismatchHandler
 }
 
-// DefaultSchemaMismatchConfig returns the default configuration
+// DefaultSchemaMismatchConfig returns the default configuration for schema mismatch handling.
+// The default config does not report unknown fields, is not strict, and has no callback.
 func DefaultSchemaMismatchConfig() SchemaMismatchConfig {
 	return SchemaMismatchConfig{
 		ReportUnknownFields: false,
@@ -55,7 +68,9 @@ func DefaultSchemaMismatchConfig() SchemaMismatchConfig {
 	}
 }
 
-// ReportSchemaMismatch reports a schema mismatch according to config
+// ReportSchemaMismatch reports a schema mismatch according to the provided config.
+// If a callback is configured, it is invoked with the mismatch details.
+// If strict mode is enabled, an error is returned. Otherwise, a warning is logged.
 func ReportSchemaMismatch(config SchemaMismatchConfig, modelName, endpoint string, missingFields, unknownFields []string, unknownValues map[string]any) error {
 	mismatch := &SchemaMismatch{
 		ModelName:      modelName,
@@ -80,18 +95,22 @@ func ReportSchemaMismatch(config SchemaMismatchConfig, modelName, endpoint strin
 	return nil
 }
 
-// SchemaMismatchTracker tracks reported mismatches to avoid duplicates
+// SchemaMismatchTracker tracks reported mismatches to avoid duplicate reports.
+// It is safe for concurrent use.
 type SchemaMismatchTracker struct {
 	mu       sync.Mutex
 	reported map[string]bool
 }
 
+// NewSchemaMismatchTracker creates a new SchemaMismatchTracker.
 func NewSchemaMismatchTracker() *SchemaMismatchTracker {
 	return &SchemaMismatchTracker{
 		reported: make(map[string]bool),
 	}
 }
 
+// ShouldReport returns true if the given model and fields have not been reported before.
+// It marks them as reported so subsequent calls return false for the same key.
 func (t *SchemaMismatchTracker) ShouldReport(modelName string, fields []string) bool {
 	t.mu.Lock()
 	defer t.mu.Unlock()