strava-ruby-client 3.0.0.pre.2 → 3.1.0

data/lib/strava/models/achievement.rb

@@ -2,10 +2,37 @@
 
 module Strava
   module Models
-    # Undocumented
+    #
+    # Represents an achievement earned during a segment effort.
+    #
+    # Achievements include overall rank on a segment, yearly/monthly/weekly records,
+    # and PR (personal record) designations. This model is not documented in the
+    # official Strava API reference.
+    #
+    # @note This model is not documented by Strava API documentation. Properties
+    #   are inferred from API responses.
+    #
+    # @see Strava::Models::DetailedSegmentEffort
+    #
+    # @example Accessing achievements from a segment effort
+    #   activity = client.activity(1234567890)
+    #   activity.segment_efforts.each do |effort|
+    #     effort.achievements.each do |achievement|
+    #       puts "#{achievement.type}: Rank #{achievement.rank}"
+    #     end
+    #   end
+    #
     class Achievement < Strava::Models::Response
+      # @return [Integer, nil] Rank or position for this achievement (e.g., 1 for first place)
+      # @note Not documented by Strava API
       property 'rank'
+
+      # @return [String, nil] Type of achievement (e.g., "overall", "pr", "year_pr")
+      # @note Not documented by Strava API
       property 'type'
+
+      # @return [Integer, nil] Numeric identifier for the achievement type
+      # @note Not documented by Strava API
       property 'type_id'
     end
   end

data/lib/strava/models/activity_stats.rb

@@ -2,18 +2,64 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-ActivityStats
+    #
+    # Represents aggregated activity statistics for an athlete.
+    #
+    # Contains totals broken down by activity type (ride, run, swim) and time period
+    # (recent, year-to-date, all-time). Recent totals cover the last 4 weeks.
+    #
+    # @example Get athlete statistics
+    #   stats = client.athlete_stats(12345)
+    #
+    #   # Recent activity
+    #   recent = stats.recent_run_totals
+    #   puts "Recent runs: #{recent.count} activities"
+    #   puts "Distance: #{recent.distance_s}"
+    #   puts "Time: #{recent.moving_time_in_hours_s}"
+    #
+    #   # Year-to-date
+    #   ytd = stats.ytd_ride_totals
+    #   puts "YTD rides: #{ytd.count} totaling #{ytd.distance_s}"
+    #
+    #   # All-time records
+    #   puts "Biggest ride: #{stats.biggest_ride_distance}m"
+    #   puts "Biggest climb: #{stats.biggest_climb_elevation_gain}m"
+    #
+    # @see ActivityTotal
+    # @see https://developers.strava.com/docs/reference/#api-models-ActivityStats
+    #
     class ActivityStats < Strava::Models::Response
+      # @return [Float] Longest ride distance in meters
       property 'biggest_ride_distance'
+
+      # @return [Float] Most elevation gain in a single activity (meters)
       property 'biggest_climb_elevation_gain'
+
+      # @return [ActivityTotal] Recent ride totals (last 4 weeks)
       property 'recent_ride_totals', transform_with: ->(v) { Strava::Models::ActivityTotal.new(v) }
+
+      # @return [ActivityTotal] Recent run totals (last 4 weeks)
       property 'recent_run_totals', transform_with: ->(v) { Strava::Models::ActivityTotal.new(v) }
+
+      # @return [ActivityTotal] Recent swim totals (last 4 weeks)
       property 'recent_swim_totals', transform_with: ->(v) { Strava::Models::ActivityTotal.new(v) }
+
+      # @return [ActivityTotal] Year-to-date ride totals
       property 'ytd_ride_totals', transform_with: ->(v) { Strava::Models::ActivityTotal.new(v) }
+
+      # @return [ActivityTotal] Year-to-date run totals
       property 'ytd_run_totals', transform_with: ->(v) { Strava::Models::ActivityTotal.new(v) }
+
+      # @return [ActivityTotal] Year-to-date swim totals
       property 'ytd_swim_totals', transform_with: ->(v) { Strava::Models::ActivityTotal.new(v) }
+
+      # @return [ActivityTotal] All-time ride totals
       property 'all_ride_totals', transform_with: ->(v) { Strava::Models::ActivityTotal.new(v) }
+
+      # @return [ActivityTotal] All-time run totals
       property 'all_run_totals', transform_with: ->(v) { Strava::Models::ActivityTotal.new(v) }
+
+      # @return [ActivityTotal] All-time swim totals
       property 'all_swim_totals', transform_with: ->(v) { Strava::Models::ActivityTotal.new(v) }
     end
   end

data/lib/strava/models/activity_total.rb

@@ -2,13 +2,37 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-ActivityTotal
+    #
+    # Represents totals for a specific activity type and time period.
+    #
+    # Contains aggregated counts, distance, time, and elevation for activities.
+    # Used within ActivityStats to break down statistics by activity type
+    # (ride, run, swim) and period (recent, YTD, all-time).
+    #
+    # Includes helper mixins for formatting distance, time, and elevation.
+    #
+    # @example Access activity totals
+    #   stats = client.athlete_stats(12345)
+    #   totals = stats.recent_run_totals
+    #   puts "#{totals.count} runs"
+    #   puts "Total distance: #{totals.distance_s}"
+    #   puts "Moving time: #{totals.moving_time_in_hours_s}"
+    #   puts "Elevation: #{totals.elevation_gain_s}"
+    #   puts "Achievements: #{totals.achievement_count}"
+    #
+    # @see ActivityStats
+    # @see https://developers.strava.com/docs/reference/#api-models-ActivityTotal
+    #
     class ActivityTotal < Strava::Models::Response
+      # @return [Integer] Number of activities
       property 'count'
+
       include Mixins::Distance
       include Mixins::MovingTime
       include Mixins::ElapsedTime
       include Mixins::ElevationGain
+
+      # @return [Integer] Total number of achievements/trophies earned
       property 'achievement_count'
     end
   end

data/lib/strava/models/activity_zone.rb

@@ -2,16 +2,53 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-ActivityZone
+    #
+    # Represents time spent in heart rate or power zones during an activity.
+    #
+    # Activity zones show how much time was spent at different intensity levels,
+    # which helps analyze training load and effort distribution. Each zone bucket
+    # contains the time spent in that zone range.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-ActivityZone Strava API ActivityZone reference
+    # @see Strava::Models::TimedZoneRange
+    # @see Strava::Api::Client#activity_zones
+    #
+    # @example Analyzing time in heart rate zones
+    #   zones = client.activity_zones(1234567890)
+    #   hr_zone = zones.find { |z| z.type == 'heartrate' }
+    #
+    #   if hr_zone
+    #     puts "Max HR: #{hr_zone.max}"
+    #     puts "Sensor-based: #{hr_zone.sensor_based}"
+    #     hr_zone.distribution_buckets.each_with_index do |bucket, i|
+    #       puts "Zone #{i + 1}: #{bucket.time} seconds (#{bucket.min}-#{bucket.max} bpm)"
+    #     end
+    #   end
+    #
     class ActivityZone < Strava::Models::Response
+      # @return [Integer, nil] Relative effort score for this activity
       property 'score'
+
+      # @return [Array<TimedZoneRange>] Array of time spent in each zone bucket
       property 'distribution_buckets', transform_with: ->(v) { v.map { |r| Strava::Models::TimedZoneRange.new(r) } }
+
+      # @return [String] Type of zone data ("heartrate" or "power")
       property 'type'
+
+      # @return [Boolean] Whether data comes from a sensor (vs. estimated)
       property 'sensor_based'
+
+      # @return [Integer, nil] Points or score accumulated in this zone
       property 'points'
+
+      # @return [Boolean] Whether custom zones are being used
       property 'custom_zones'
+
+      # @return [Integer, nil] Maximum value recorded (e.g., max heart rate in bpm)
       property 'max'
-      # undocumented
+
+      # @return [Integer] Resource state indicator
+      # @note Not documented by Strava API
       property 'resource_state'
     end
   end

data/lib/strava/models/authorization.rb

@@ -2,7 +2,20 @@
 
 module Strava
   module Models
+    #
+    # Represents an authorization deauthorization response.
+    #
+    # This model is returned when revoking access to an athlete's data.
+    # It contains the access token that was revoked.
+    #
+    # @example Deauthorize an athlete
+    #   authorization = client.deauthorize
+    #   puts "Revoked token: #{authorization.access_token}"
+    #
+    # @see Strava::Api::Client#deauthorize
+    #
     class Authorization < Strava::Models::Response
+      # @return [String] The access token that was revoked
       property 'access_token'
     end
   end

data/lib/strava/models/base_stream.rb

@@ -2,10 +2,31 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-BaseStream
+    #
+    # Represents base stream metadata from the Strava API.
+    #
+    # Streams are time-series data for activities such as GPS coordinates, heart rate,
+    # power, cadence, etc. The BaseStream provides metadata about how the stream data
+    # was sampled and processed.
+    #
+    # @see https://developers.strava.com/docs/reference/#api-models-BaseStream Strava API BaseStream reference
+    # @see Strava::Models::Stream
+    # @see Strava::Models::StreamSet
+    #
+    # @example Accessing stream metadata
+    #   streams = client.activity_streams(1234567890, keys: 'heartrate,watts')
+    #   puts streams.heartrate.original_size  # => 3600
+    #   puts streams.heartrate.resolution     # => "high"
+    #   puts streams.heartrate.series_type    # => "distance"
+    #
     class BaseStream < Strava::Models::Response
+      # @return [Integer] Total number of data points in the original stream before any resampling
       property 'original_size'
+
+      # @return [String] Resolution of the stream data ("low", "medium", or "high")
       property 'resolution'
+
+      # @return [String] Type of series - how data points are indexed ("time" or "distance")
       property 'series_type'
     end
   end

data/lib/strava/models/club_event.rb

@@ -2,29 +2,92 @@
 
 module Strava
   module Models
-    # Unodcumented
+    #
+    # Represents a club group event or ride.
+    #
+    # Club events are organized group activities where club members can join
+    # to ride, run, or participate together. Events can be recurring and may
+    # include a specific route.
+    #
+    # @example List club events
+    #   events = client.club_events(12345)
+    #   events.each do |event|
+    #     puts event.title
+    #     puts event.description
+    #     puts "Organized by: #{event.organizing_athlete.name}"
+    #     puts "Activity type: #{event.activity_type}"
+    #     puts "Next occurrence: #{event.upcoming_occurrences.first}"
+    #     puts event.strava_url
+    #   end
+    #
+    # @see Strava::Api::Client#club_events
+    #
     class ClubEvent < Strava::Models::Response
+      # @return [Integer] Event identifier
       property 'id'
+
+      # @return [Integer] Resource state indicator
       property 'resource_state'
+
+      # @return [String] Event title
       property 'title'
+
+      # @return [String] Event description
       property 'description'
+
+      # @return [Integer] Club identifier
       property 'club_id'
+
+      # @return [SummaryClub] The club hosting this event
       property 'club', transform_with: ->(c) { Strava::Models::SummaryClub.new(c) }
+
+      # @return [SummaryAthlete] Athlete organizing the event
       property 'organizing_athlete', transform_with: ->(oa) { Strava::Models::SummaryAthlete.new(oa) }
+
+      # @return [String] Type of activity (e.g., "Ride", "Run")
       property 'activity_type'
+
+      # @return [Time] When the event was created
       property 'created_at', transform_with: ->(v) { Time.parse(v) if v&.length&.positive? }
+
+      # @return [Integer, nil] Associated route identifier
       property 'route_id'
+
+      # @return [Route, nil] Associated route details
       property 'route', transform_with: ->(r) { Strava::Models::Route.new(r) }
+
+      # @return [Boolean] Whether event is for women only
       property 'women_only'
+
+      # @return [Boolean] Whether event is private
       property 'private'
+
+      # @return [Array<Integer>] Skill levels for participants (0-5 scale)
       property 'skill_levels'
+
+      # @return [Array<Integer>] Terrain types (e.g., road, trail, mixed)
       property 'terrain'
+
+      # @return [Array<Time>] Upcoming scheduled occurrences of this event
       property 'upcoming_occurrences', transform_with: ->(upcoming) { upcoming.map { |o| Time.parse(o) } }
+
+      # @return [String] Timezone for the event
       property 'zone'
+
+      # @return [String] Event meeting address
       property 'address'
+
+      # @return [Boolean] Whether authenticated athlete has joined this event
       property 'joined'
+
+      # @return [LatLng] Starting location coordinates
       property 'start_latlng', transform_with: ->(v) { Strava::Models::LatLng.new(v) }
 
+      #
+      # Returns the Strava web URL for this event.
+      #
+      # @return [String] Full URL to view the event on Strava.com
+      #
       def strava_url
         "https://www.strava.com/clubs/#{club_id}/group_events/#{id}"
       end

data/lib/strava/models/comment.rb

@@ -2,17 +2,55 @@
 
 module Strava
   module Models
+    #
+    # Represents a comment on a Strava activity.
+    #
+    # Comments are text messages left by athletes on activities. Each comment
+    # includes the text content, the athlete who made the comment, and timestamp.
+    #
+    # @example List activity comments
+    #   comments = client.activity_comments(1234567890)
+    #   comments.each do |comment|
+    #     puts "#{comment.athlete.name}: #{comment.text}"
+    #     puts "Posted at: #{comment.created_at}"
+    #   end
+    #
+    # @see Strava::Api::Client#activity_comments
+    #
     class Comment < Strava::Models::Response
+      # @return [Integer] Comment ID
       property 'id'
+
+      # @return [Integer] ID of the activity this comment is on
       property 'activity_id'
+
+      # @return [String] The comment text
       property 'text'
+
+      # @return [Time] When the comment was created
       property 'created_at', transform_with: ->(v) { Time.parse(v) }
+
+      # @return [SummaryAthlete] The athlete who made the comment
       property 'athlete', transform_with: ->(v) { Strava::Models::SummaryAthlete.new(v) }
-      # undocumented
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Associated post ID
       property 'post_id'
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Resource state indicator
       property 'resource_state'
+
+      # @note Undocumented in official API
+      # @return [Hash, nil] Metadata about @mentions in the comment
       property 'mentions_metadata'
+
+      # @note Undocumented in official API
+      # @return [Integer, nil] Number of reactions on this comment
       property 'reaction_count'
+
+      # @note Undocumented in official API
+      # @return [Boolean, nil] Whether the authenticated athlete has reacted to this comment
       property 'has_reacted'
     end
   end

data/lib/strava/models/destination.rb

@@ -2,10 +2,37 @@
 
 module Strava
   module Models
-    # Undocumented
+    #
+    # Represents a destination or link reference.
+    #
+    # Used to provide navigation links to related resources or pages.
+    # This model is not documented in the official Strava API reference.
+    #
+    # @note This model is not documented by Strava API documentation. Properties
+    #   are inferred from API responses.
+    #
+    # @see Strava::Models::Xoms
+    # @see Strava::Models::LocalLegend
+    #
+    # @example Accessing destination information
+    #   # From XOMs or local legend data
+    #   if xoms.destination
+    #     puts "Name: #{xoms.destination.name}"
+    #     puts "Type: #{xoms.destination.type}"
+    #     puts "Link: #{xoms.destination.href}"
+    #   end
+    #
     class Destination < Strava::Models::Response
+      # @return [String, nil] URL or path to the destination resource
+      # @note Not documented by Strava API
       property 'href'
+
+      # @return [String, nil] Type of destination (e.g., "segment")
+      # @note Not documented by Strava API
       property 'type'
+
+      # @return [String, nil] Display name of the destination
+      # @note Not documented by Strava API
       property 'name'
     end
   end