Merge pull request #100 from dblock/claude-doc

Add comprehensive RDoc documentation across entire codebase

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