Add comprehensive RDoc documentation across entire codebase

This commit adds complete RDoc documentation to the strava-ruby-client library,
achieving 100% documentation coverage across all classes, modules, methods, and properties.

## API Endpoints Documentation

### Module-Level Documentation Added
- Clubs: Club members, activities, and administrators
- Streams: Time-series activity data (altitude, cadence, heartrate, etc.)
- Routes: Route planning and export (GPX/TCX)
- Uploads: Activity file upload and processing
- SegmentEfforts: Athlete segment attempt tracking
- Gears: Equipment (bikes/shoes) management
- OAuth: Token deauthorization

### Method Parameter Documentation Fixed
Fixed 18 methods with id_or_options parameters to correctly document:
- @param id_or_options [String, Integer, Hash] with proper type signatures
- Added examples showing both calling patterns (ID as arg vs. in hash)
- Affected endpoints: Clubs, Streams, Routes, Uploads, SegmentEfforts, Gears, Segments

### Enhanced Method Documentation
- starred_segments, segment, star_segment: Added @return, @example, @yield tags
- deauthorize: Added complete @param, @return, @example documentation

## Core Infrastructure Documentation

### Web Layer
- Web::Client: Base client class with full method documentation
- Web::Connection: HTTP connection management and Faraday configuration
- Web::Request: GET/POST/PUT/DELETE methods with @param/@return tags
- Web::Response: Response wrapping with method_missing documentation
- RaiseResponseError: Middleware error handling with status code mapping

### Error Classes
- Fault: Base error class with message/headers/errors accessors
- RatelimitError: Rate limit errors with @see links to documentation
- UploadError: Upload processing errors with status information

### Configuration Modules
- Api::Config: API client configuration with examples
- Web::Config: HTTP settings (proxy, SSL, timeouts)
- OAuth::Config: OAuth credentials configuration
- Webhooks::Config: Webhook subscription configuration
- All configs now have configure/config class methods documented

### Utility Classes
- Logger: Default logger with customization examples
- DeepCopyable: Deep copy mixin with usage examples
- Pagination: Collection iteration with method_missing delegation

## Model Documentation

### Properties Documented (221+ total)
Added @return tags with type information and descriptions for all properties in:

**Detailed Models:**
- DetailedActivity (53 properties): All activity metrics, flags, and relationships
- DetailedAthlete (30 properties): Complete athlete profile information
- DetailedSegment (29 properties): Segment location, elevation, and statistics

**Summary Models:**
- SummaryActivity (51 properties): Essential activity information
- SummaryAthlete (14 properties): Basic athlete profile
- Lap (24 properties): Lap metrics and timing
- Route (20 properties): Route planning information

**Other Models:**
- Comment (5 undocumented properties): Reactions, mentions metadata
- Subscription: Webhook subscription details

### Undocumented Properties Marked
All properties not in official Strava API documentation marked with:
- @note Undocumented in official API
- Clear descriptions of observed behavior
- Examples: visibility, location data, heart rate options, leaderboard settings

## Documentation Standards Applied

All documentation follows RDoc conventions:
- @param with types and descriptions
- @option for hash parameters
- @return with return types
- @yield for block parameters
- @example with practical usage
- @see for cross-references to related classes and Strava API docs
- @note for unofficial/undocumented features
- @api private for internal methods
- @raise for exception documentation

## Files Modified
102 files updated with comprehensive RDoc documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: dblock

CHANGELOG.md

@@ -1,5 +1,6 @@
-### 3.0.1 (Next)
+### 3.1.0 (Next)
 
+* [#100](https://github.com/dblock/strava-ruby-client/pull/100): Adds comprehensive rdoc documentation - [@dblock](https://github.com/dblock).
 * Your contribution here.
 
 ### 3.0.0 (2025/10/24)

lib/strava/api/client.rb

@@ -2,6 +2,33 @@
 
 module Strava
   module Api
+    #
+    # Main API client for interacting with the Strava API v3.
+    #
+    # This class provides a complete Ruby interface to the Strava API, including support for:
+    # * Activities (create, read, update, list)
+    # * Athletes (profile, stats, zones)
+    # * Clubs (details, members, activities)
+    # * Gear (equipment details)
+    # * Routes (details, GPX/TCX export)
+    # * Segments and Segment Efforts
+    # * Streams (activity, route, segment data)
+    # * Uploads (activity file uploads)
+    # * OAuth (token refresh, deauthorization)
+    #
+    # @example Create a client with an access token
+    #   client = Strava::Api::Client.new(access_token: "your_access_token")
+    #   athlete = client.athlete
+    #   activities = client.athlete_activities(per_page: 10)
+    #
+    # @example Configure globally
+    #   Strava::Api::Client.configure do |config|
+    #     config.access_token = "your_access_token"
+    #   end
+    #   client = Strava::Api::Client.new
+    #
+    # @see https://developers.strava.com/docs/reference/ Strava API Documentation
+    #
     class Client < Strava::Web::Client
       include Endpoints::Activities
       include Endpoints::Athletes
@@ -16,22 +43,64 @@ class Client < Strava::Web::Client
 
       attr_accessor(*Config::ATTRIBUTES)
 
+      #
+      # Initialize a new API client.
+      #
+      # @param [Hash] options Configuration options for the client
+      # @option options [String] :access_token OAuth access token for API authentication (required)
+      # @option options [String] :endpoint API endpoint URL (defaults to https://www.strava.com/api/v3)
+      # @option options [String] :user_agent User agent string for HTTP requests
+      # @option options [Logger] :logger Logger instance for request/response logging
+      # @option options [Integer] :timeout HTTP request timeout in seconds
+      # @option options [Integer] :open_timeout HTTP connection timeout in seconds
+      # @option options [String] :proxy HTTP proxy URL
+      # @option options [String] :ca_path Path to SSL CA certificates
+      # @option options [String] :ca_file Path to SSL CA certificate file
+      #
+      # @example
+      #   client = Strava::Api::Client.new(
+      #     access_token: "your_access_token",
+      #     user_agent: "My Strava App/1.0"
+      #   )
+      #
       def initialize(options = {})
         Config::ATTRIBUTES.each do |key|
           send("#{key}=", options[key] || Strava::Api.config.send(key))
         end
         super
       end
 
+      #
+      # Returns HTTP headers for API requests.
+      #
+      # @return [Hash] Headers including OAuth bearer token authorization
+      # @api private
+      #
       def headers
         { 'Authorization' => "Bearer #{access_token}" }
       end
 
       class << self
+        #
+        # Configure the API client globally.
+        #
+        # @yield [Config] Configuration object
+        # @return [Strava::Api::Config] Configuration object
+        #
+        # @example
+        #   Strava::Api::Client.configure do |config|
+        #     config.access_token = "your_access_token"
+        #   end
+        #
         def configure
           block_given? ? yield(Config) : Config
         end
 
+        #
+        # Returns the configuration object.
+        #
+        # @return [Strava::Api::Config] Configuration object
+        #
         def config
           Config
         end

lib/strava/api/config.rb

@@ -2,27 +2,67 @@
 
 module Strava
   module Api
+    #
+    # Configuration module for the Strava API client.
+    #
+    # This module manages configuration settings for the API client, including
+    # the API endpoint URL and access token for authentication.
+    #
+    # @example Configure the API client
+    #   Strava::Api.configure do |config|
+    #     config.access_token = 'your_access_token_here'
+    #   end
+    #
+    # @example Access current configuration
+    #   Strava::Api.config.endpoint
+    #   # => 'https://www.strava.com/api/v3'
+    #
     module Config
       extend self
 
+      # @return [Array<Symbol>] List of configurable attributes
       ATTRIBUTES = %i[
         endpoint
         access_token
       ].freeze
 
       attr_accessor(*Config::ATTRIBUTES)
 
+      #
+      # Reset configuration to default values.
+      #
+      # Sets the endpoint to the default Strava API v3 URL and
+      # clears the access token.
+      #
+      # @return [void]
+      #
       def reset
         self.endpoint = 'https://www.strava.com/api/v3'
         self.access_token = nil
       end
     end
 
     class << self
+      #
+      # Configure the API client with a block.
+      #
+      # @yield [Config] Yields the configuration module for setup
+      # @return [Module] The Config module
+      #
+      # @example
+      #   Strava::Api.configure do |config|
+      #     config.access_token = ENV['STRAVA_ACCESS_TOKEN']
+      #   end
+      #
       def configure
         block_given? ? yield(Config) : Config
       end
 
+      #
+      # Returns the current API configuration.
+      #
+      # @return [Module] The Config module
+      #
       def config
         Config
       end

lib/strava/api/cursor.rb

@@ -2,11 +2,42 @@
 
 module Strava
   module Api
+    #
+    # Handles paginated iteration through API endpoints.
+    #
+    # This class provides an Enumerable interface for iterating through
+    # paginated API responses. It supports both traditional page-based
+    # pagination and cursor-based pagination.
+    #
+    # @see Strava::Api::Pagination
+    #
+    # @example Iterating through pages
+    #   cursor = Strava::Api::Cursor.new(client, 'athlete/activities', per_page: 30)
+    #   cursor.each do |page|
+    #     page.each do |activity|
+    #       puts activity.name
+    #     end
+    #   end
+    #
     class Cursor
       include Enumerable
 
-      attr_reader :client, :path, :params
+      # @return [Strava::Api::Client] API client instance
+      attr_reader :client
 
+      # @return [String] API endpoint path
+      attr_reader :path
+
+      # @return [Hash] Query parameters for the request
+      attr_reader :params
+
+      #
+      # Initialize a new Cursor for paginated iteration.
+      #
+      # @param client [Strava::Api::Client] API client to use for requests
+      # @param path [String] API endpoint path to paginate
+      # @param params [Hash] Query parameters (excluding :limit which is removed)
+      #
       def initialize(client, path, params = {})
         @client = client
         @path = path