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

data/lib/strava/models/lat_lng.rb

@@ -2,27 +2,66 @@
 
 module Strava
   module Models
+    #
+    # Represents geographic coordinates (latitude/longitude).
+    #
+    # This is a helper class for working with geographic coordinates in Strava data.
+    # Coordinates are stored as an array [latitude, longitude] and can be accessed
+    # via helper methods or array syntax.
+    #
+    # @example Accessing coordinates
+    #   activity = client.activity(1234567890)
+    #   start = activity.start_latlng
+    #   puts "Latitude: #{start.lat}"
+    #   puts "Longitude: #{start.lng}"
+    #   puts "Array: #{start.to_a.inspect}"  # [40.7128, -74.0060]
+    #
+    # @example Creating coordinates
+    #   coords = Strava::Models::LatLng.new([40.7128, -74.0060])
+    #   coords.lat  # => 40.7128
+    #   coords.lng  # => -74.0060
+    #
     class LatLng
+      # @return [Array<Float>] Coordinates as [latitude, longitude]
       attr_accessor :latlng
 
+      #
+      # Initialize with coordinates.
+      #
+      # @param latlng [Array<Float>, nil] Coordinates as [latitude, longitude]
+      #
+      def initialize(latlng = nil)
+        @latlng = latlng
+      end
+
+      # @return [Float, nil] Latitude
       def lat
         @latlng[0]
       end
 
+      # @return [Float, nil] Longitude
       def lng
         @latlng[1]
       end
 
+      # @param value [Float] Latitude value
       def lat=(value)
         @latlng ||= [nil, nil]
         @latlng[0] = value
       end
 
+      # @param value [Float] Longitude value
       def lng=(value)
         @latlng ||= [nil, nil]
         @latlng[1] = value
       end
 
+      #
+      # Compare with another LatLng or Array.
+      #
+      # @param other [LatLng, Array] Object to compare with
+      # @return [Boolean] true if coordinates are equal
+      #
       def ==(other)
         case other
         when LatLng
@@ -34,6 +73,7 @@ module Strava
         end
       end
 
+      # @return [Array<Float>] Coordinates as array [latitude, longitude]
       def to_a
         @latlng
       end
@@ -41,19 +81,17 @@ module Strava
       alias to_h to_a
       alias as_json to_a
 
+      # @return [String] JSON representation
       def to_json(*args)
         as_json.to_json(args)
       end
 
+      # @return [String] String representation of coordinates
       def inspect
         @latlng.inspect
       end
 
       alias to_s inspect
-
-      def initialize(latlng = nil)
-        @latlng = latlng
-      end
     end
   end
 end

data/lib/strava/models/local_legend.rb

@@ -2,14 +2,54 @@
 
 module Strava
   module Models
-    # Undocumented
+    #
+    # Represents Local Legend status on a segment.
+    #
+    # Local Legends are athletes with the most efforts on a segment in the last 90 days.
+    # This model contains information about the current local legend for a segment.
+    # 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::DetailedSegment
+    #
+    # @example Accessing local legend information
+    #   segment = client.segment(1234567)
+    #   if segment.local_legend
+    #     legend = segment.local_legend
+    #     puts "Local Legend: #{legend.title}"
+    #     puts "Athlete ID: #{legend.athlete_id}"
+    #     puts "#{legend.effort_description} (#{legend.effort_count} efforts)"
+    #   end
+    #
     class LocalLegend < Strava::Models::Response
+      # @return [Integer, nil] ID of the athlete who is the local legend
+      # @note Not documented by Strava API
       property 'athlete_id'
+
+      # @return [String, nil] Title or name of the local legend
+      # @note Not documented by Strava API
       property 'title'
+
+      # @return [String, nil] URL to the athlete's profile picture
+      # @note Not documented by Strava API
       property 'profile'
+
+      # @return [String, nil] Description of the effort count (e.g., "X efforts in the last 90 days")
+      # @note Not documented by Strava API
       property 'effort_description'
+
+      # @return [Integer, nil] Number of efforts by this athlete in the qualifying period
+      # @note Not documented by Strava API
       property 'effort_count'
+
+      # @return [Hash, nil] Detailed effort count data
+      # @note Not documented by Strava API
       property 'effort_counts'
+
+      # @return [Destination, nil] Link to related resource
+      # @note Not documented by Strava API
       property 'destination'
     end
   end

data/lib/strava/models/map.rb

@@ -2,10 +2,41 @@
 
 module Strava
   module Models
+    #
+    # Represents a map with polyline data for an activity, route, or segment.
+    #
+    # Maps contain encoded polyline data that represents the geographic path.
+    # The polyline format uses Google's encoded polyline algorithm which can
+    # be decoded using libraries like the 'polylines' gem.
+    #
+    # @example Decode and use polyline data
+    #   require 'polylines'
+    #
+    #   activity = client.activity(1234567890)
+    #   map = activity.map
+    #
+    #   # Decode the summary polyline
+    #   decoded = Polylines::Decoder.decode_polyline(map.summary_polyline)
+    #   start_point = decoded.first  # [latitude, longitude]
+    #   end_point = decoded.last
+    #
+    #   # Use with Google Maps Static API
+    #   url = "https://maps.googleapis.com/maps/api/staticmap?" \
+    #         "path=enc:#{CGI.escape(map.summary_polyline)}&size=800x800"
+    #
+    # @see https://developers.google.com/maps/documentation/utilities/polylinealgorithm
+    #
     class Map < Strava::Models::Response
+      # @return [String] Map identifier
       property 'id'
+
+      # @return [String] Google polyline encoding of the route (lower resolution)
       property 'summary_polyline'
+
+      # @return [Integer] Resource state indicator
       property 'resource_state'
+
+      # @return [String] Google polyline encoding of the route (higher resolution)
       property 'polyline'
     end
   end

data/lib/strava/models/meta_activity.rb

@@ -2,11 +2,24 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-MetaActivity
+    #
+    # Represents minimal activity information (meta level).
+    #
+    # Meta models contain only essential identifying information.
+    # Used in contexts where only basic activity reference is needed.
+    #
+    # @see SummaryActivity
+    # @see DetailedActivity
+    # @see https://developers.strava.com/docs/reference/#api-models-MetaActivity
+    #
     class MetaActivity < Strava::Models::Response
+      # @return [Integer] Activity identifier
       property 'id'
-      # undocumented
+
+      # @return [Integer] Resource state indicator (1=meta)
       property 'resource_state'
+
+      # @return [String] Activity visibility (e.g., "everyone", "followers_only", "only_me")
       property 'visibility'
     end
   end

data/lib/strava/models/meta_athlete.rb

@@ -2,12 +2,27 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-MetaAthlete
+    #
+    # Represents minimal athlete information (meta level).
+    #
+    # Meta models contain only essential identifying information without
+    # detailed data. Used in contexts where only basic athlete reference is needed.
+    #
+    # @see SummaryAthlete
+    # @see DetailedAthlete
+    # @see https://developers.strava.com/docs/reference/#api-models-MetaAthlete
+    #
     class MetaAthlete < Strava::Models::Response
+      # @return [Integer, nil] Athlete identifier (may be nil for privacy)
       property 'id'
-      # undocumented
+
+      # @return [Integer] Resource state indicator (1=meta)
       property 'resource_state'
+
+      # @return [String, nil] Athlete's first name
       property 'firstname'
+
+      # @return [String, nil] Athlete's last name
       property 'lastname'
     end
   end

data/lib/strava/models/meta_club.rb

@@ -2,10 +2,24 @@
 
 module Strava
   module Models
-    # https://developers.strava.com/docs/reference/#api-models-MetaClub
+    #
+    # Represents minimal club information (meta level).
+    #
+    # Meta models contain only essential identifying information.
+    # Used in contexts where only basic club reference is needed.
+    #
+    # @see SummaryClub
+    # @see DetailedClub
+    # @see https://developers.strava.com/docs/reference/#api-models-MetaClub
+    #
     class MetaClub < Strava::Models::Response
+      # @return [Integer] Club identifier
       property 'id'
+
+      # @return [Integer] Resource state indicator (1=meta)
       property 'resource_state'
+
+      # @return [String] Club name
       property 'name'
     end
   end

data/lib/strava/models/mixins/average_speed.rb

@@ -3,54 +3,132 @@
 module Strava
   module Models
     module Mixins
+      #
+      # Provides average speed and pace conversion methods.
+      #
+      # This mixin adds the average_speed property (stored in meters per second)
+      # and provides helper methods to convert it to various speed and pace formats.
+      # Pace is the inverse of speed (time per distance) and is commonly used for running.
+      #
+      # @example Using speed and pace helpers
+      #   activity = client.activity(1234567890)
+      #   puts activity.average_speed                    # => 3.5 (m/s)
+      #   puts activity.average_speed_s                  # => "12.6km/h"
+      #   puts activity.average_speed_miles_per_hour_s   # => "7.8mph"
+      #   puts activity.pace_per_kilometer_s             # => "4m45s/km"
+      #   puts activity.pace_per_mile_s                  # => "7m40s/mi"
+      #
       module AverageSpeed
         extend ActiveSupport::Concern
 
         included do
+          # @return [Float] Average speed in meters per second
           property 'average_speed'
         end
 
-        # always in meters per second, even in imperial splits
+        #
+        # Returns average speed in meters per second (same as average_speed).
+        #
+        # @return [Float] Average speed in m/s
+        #
+        # @note Always in meters per second, even in imperial splits
+        #
         def average_speed_meters_per_second
           average_speed
         end
 
+        #
+        # Returns pace per mile.
+        #
+        # @return [String, nil] Pace formatted as "Xm%Ys/mi" (e.g., "7m30s/mi")
+        #
         def pace_per_mile_s
           convert_meters_per_second_to_pace average_speed, :mi
         end
 
+        #
+        # Returns pace per 100 yards (swimming).
+        #
+        # @return [String, nil] Pace formatted as "XmYs/100yd"
+        #
         def pace_per_100_yards_s
           convert_meters_per_second_to_pace average_speed, :'100yd'
         end
 
+        #
+        # Returns pace per 100 meters (swimming).
+        #
+        # @return [String, nil] Pace formatted as "XmYs/100m"
+        #
         def pace_per_100_meters_s
           convert_meters_per_second_to_pace average_speed, :'100m'
         end
 
+        #
+        # Returns pace per kilometer.
+        #
+        # @return [String, nil] Pace formatted as "XmYs/km" (e.g., "4m30s/km")
+        #
         def pace_per_kilometer_s
           convert_meters_per_second_to_pace average_speed, :km
         end
 
+        #
+        # Returns average speed in kilometers per hour.
+        #
+        # @return [String, nil] Speed formatted as "X.Xkm/h"
+        #
         def average_speed_kilometer_per_hour_s
           return unless average_speed&.positive?
 
           format('%.1fkm/h', average_speed * 3.6)
         end
 
+        #
+        # Returns average speed in miles per hour.
+        #
+        # @return [String, nil] Speed formatted as "X.Xmph"
+        #
         def average_speed_miles_per_hour_s
           return unless average_speed&.positive?
 
           format('%.1fmph', average_speed * 2.23694)
         end
 
+        #
+        # Returns default formatted average speed (kilometers per hour).
+        #
+        # @return [String, nil] Speed formatted as "X.Xkm/h"
+        #
         def average_speed_s
           average_speed_kilometer_per_hour_s
         end
 
+        #
+        # Returns default formatted pace (per kilometer).
+        #
+        # @return [String, nil] Pace formatted as "XmYs/km"
+        #
+        def pace_s
+          pace_per_kilometer_s
+        end
+
         private
 
-        # Convert speed (m/s) to pace (min/mile or min/km) in the format of 'x:xx'
-        # http://yizeng.me/2017/02/25/convert-speed-to-pace-programmatically-using-ruby
+        #
+        # Converts speed in meters per second to pace (time per distance).
+        #
+        # Pace is calculated as the inverse of speed. For example, running at 3.33 m/s
+        # equals a 5:00/km pace (1000m / 3.33m/s = 300 seconds = 5 minutes).
+        #
+        # @param speed [Float, nil] Speed in meters per second
+        # @param unit [Symbol] Unit for pace calculation (:mi, :km, :'100yd', :'100m')
+        # @return [String, nil] Formatted pace string or nil if speed is nil/zero
+        #
+        # @see http://yizeng.me/2017/02/25/convert-speed-to-pace-programmatically-using-ruby
+        #
+        # @api private
+        #
         def convert_meters_per_second_to_pace(speed, unit = :mi)
           return unless speed&.positive?
 

data/lib/strava/models/mixins/distance.rb

@@ -3,57 +3,82 @@
 module Strava
   module Models
     module Mixins
+      #
+      # Provides distance conversion and formatting methods.
+      #
+      # This mixin is included in models that have a distance property, such as
+      # activities, laps, segments, and routes. It provides helper methods to
+      # convert and format distances in various units.
+      #
+      # @example Using distance helpers
+      #   activity = client.activity(1234567890)
+      #   puts activity.distance              # => 10000.0 (meters)
+      #   puts activity.distance_s            # => "10.0km"
+      #   puts activity.distance_in_miles_s   # => "6.21mi"
+      #   puts activity.distance_in_yards_s   # => "10936.1yd"
+      #
       module Distance
         extend ActiveSupport::Concern
 
         included do
+          # @return [Float] Distance in meters
           property 'distance'
         end
 
+        # @return [Float] Distance in meters
         def distance_in_meters
           distance
         end
 
+        # @return [Float] Distance in feet
         def distance_in_feet
           distance * 3.28084
         end
 
+        # @return [Float] Distance in miles
         def distance_in_miles
           distance_in_meters * 0.00062137
         end
 
+        # @return [String, nil] Formatted distance in miles (e.g., "6.21mi")
         def distance_in_miles_s
           return unless distance&.positive?
 
           format('%gmi', format('%.2f', distance_in_miles))
         end
 
+        # @return [Float] Distance in yards
         def distance_in_yards
           distance_in_meters * 1.09361
         end
 
+        # @return [String, nil] Formatted distance in yards (e.g., "10936.1yd")
         def distance_in_yards_s
           return unless distance&.positive?
 
           format('%gyd', format('%.1f', distance_in_yards))
         end
 
+        # @return [String, nil] Formatted distance in meters (e.g., "10000m")
         def distance_in_meters_s
           return unless distance&.positive?
 
           format('%gm', format('%d', distance_in_meters))
         end
 
+        # @return [Float] Distance in kilometers
         def distance_in_kilometers
           distance_in_meters / 1000
         end
 
+        # @return [String, nil] Formatted distance in kilometers (e.g., "10.0km")
         def distance_in_kilometers_s
           return unless distance&.positive?
 
           format('%gkm', format('%.2f', distance_in_kilometers))
         end
 
+        # @return [String, nil] Default formatted distance (same as distance_in_kilometers_s)
         def distance_s
           distance_in_kilometers_s
         end

data/lib/strava/models/mixins/elapsed_time.rb

@@ -3,14 +3,32 @@
 module Strava
   module Models
     module Mixins
+      #
+      # Provides elapsed time formatting methods.
+      #
+      # Elapsed time is the total time from start to finish of an activity, including
+      # stopped/paused time. This mixin adds the elapsed_time property and a helper
+      # method to format it as hours/minutes/seconds.
+      #
+      # @example Using elapsed time helpers
+      #   activity = client.activity(1234567890)
+      #   puts activity.elapsed_time              # => 4200 (seconds)
+      #   puts activity.elapsed_time_in_hours_s   # => "1h10m"
+      #
       module ElapsedTime
         extend ActiveSupport::Concern
         include TimeInHours
 
         included do
+          # @return [Integer] Total elapsed time in seconds (includes stopped time)
           property 'elapsed_time'
         end
 
+        #
+        # Returns formatted elapsed time as hours, minutes, and seconds.
+        #
+        # @return [String, nil] Formatted time string (e.g., "1h23m45s", "45m30s", "30s")
+        #
         def elapsed_time_in_hours_s
           time_in_hours_s elapsed_time
         end

data/lib/strava/models/mixins/elevation_difference.rb

@@ -3,33 +3,75 @@
 module Strava
   module Models
     module Mixins
+      #
+      # Provides elevation difference conversion and formatting methods.
+      #
+      # Elevation difference represents the net elevation change (can be positive
+      # or negative) for a split or segment. This differs from elevation_gain which
+      # only counts upward movement.
+      #
+      # This mixin adds the elevation_difference property and helper methods to
+      # convert and format it in meters or feet.
+      #
+      # @example Using elevation difference helpers
+      #   split = activity.splits_metric.first
+      #   puts split.elevation_difference              # => -15.2 (meters, downhill)
+      #   puts split.elevation_difference_s            # => "-15.2m"
+      #   puts split.elevation_difference_in_feet_s    # => "-49.9ft"
+      #
       module ElevationDifference
         extend ActiveSupport::Concern
 
         included do
+          # @return [Float] Net elevation difference in meters (positive = uphill, negative = downhill)
           property 'elevation_difference'
         end
 
+        #
+        # Returns elevation difference in feet.
+        #
+        # @return [Float] Elevation difference in feet
+        #
         def elevation_difference_in_feet
           elevation_difference * 3.28084
         end
 
+        #
+        # Returns elevation difference in meters (same as elevation_difference).
+        #
+        # @return [Float] Elevation difference in meters
+        #
         def elevation_difference_in_meters
           elevation_difference
         end
 
+        #
+        # Returns formatted elevation difference in meters.
+        #
+        # @return [String, nil] Formatted elevation (e.g., "15.2m" or "-15.2m")
+        #
         def elevation_difference_in_meters_s
           return if elevation_difference.nil?
 
           format('%gm', format('%.1f', elevation_difference_in_meters))
         end
 
+        #
+        # Returns formatted elevation difference in feet.
+        #
+        # @return [String, nil] Formatted elevation (e.g., "49.9ft" or "-49.9ft")
+        #
         def elevation_difference_in_feet_s
           return if elevation_difference.nil?
 
           format('%gft', format('%.1f', elevation_difference_in_feet))
         end
 
+        #
+        # Returns default formatted elevation difference (meters).
+        #
+        # @return [String, nil] Formatted elevation (e.g., "15.2m" or "-15.2m")
+        #
         def elevation_difference_s
           elevation_difference_in_meters_s
         end

data/lib/strava/models/mixins/elevation_gain.rb

@@ -3,33 +3,72 @@
 module Strava
   module Models
     module Mixins
+      #
+      # Provides elevation gain conversion and formatting methods.
+      #
+      # Elevation gain represents the total upward elevation change during an activity.
+      # This mixin adds the elevation_gain property and helper methods to convert
+      # and format it in meters or feet.
+      #
+      # @example Using elevation gain helpers
+      #   route = client.route(1234567)
+      #   puts route.elevation_gain              # => 450.5 (meters)
+      #   puts route.elevation_gain_s            # => "450.5m"
+      #   puts route.elevation_gain_in_feet_s    # => "1478.0ft"
+      #
       module ElevationGain
         extend ActiveSupport::Concern
 
         included do
+          # @return [Float] Elevation gain in meters
           property 'elevation_gain'
         end
 
+        #
+        # Returns elevation gain in feet.
+        #
+        # @return [Float] Elevation gain in feet
+        #
         def elevation_gain_in_feet
           elevation_gain * 3.28084
         end
 
+        #
+        # Returns elevation gain in meters (same as elevation_gain).
+        #
+        # @return [Float] Elevation gain in meters
+        #
         def elevation_gain_in_meters
           elevation_gain
         end
 
+        #
+        # Returns formatted elevation gain in meters.
+        #
+        # @return [String, nil] Formatted elevation (e.g., "450.5m")
+        #
         def elevation_gain_in_meters_s
           return if elevation_gain.nil?
 
           format('%gm', format('%.1f', elevation_gain_in_meters))
         end
 
+        #
+        # Returns formatted elevation gain in feet.
+        #
+        # @return [String, nil] Formatted elevation (e.g., "1478.0ft")
+        #
         def elevation_gain_in_feet_s
           return if elevation_gain.nil?
 
           format('%gft', format('%.1f', elevation_gain_in_feet))
         end
 
+        #
+        # Returns default formatted elevation gain (meters).
+        #
+        # @return [String, nil] Formatted elevation (e.g., "450.5m")
+        #
         def elevation_gain_s
           elevation_gain_in_meters_s
         end