Add YARD docs for UPS

lib/friendly_shipping/services/ups.rb

@@ -65,7 +65,7 @@ def carriers
 
       # Get rates for a shipment
       # @param [Physical::Shipment] shipment The shipment we want to get rates for
-      # @param [FriendlyShipping::Services::Ups::RateEstimateOptions] options What options
+      # @param [RateEstimateOptions] options What options
       #    to use for this rate estimate call
       # @return [Result<ApiResult<Array<Rate>>>] The rates returned from UPS encoded in a
       #   `FriendlyShipping::ApiResult` object.
@@ -87,7 +87,7 @@ def rate_estimates(shipment, options:, debug: false)
 
       # Get timing information for a shipment
       # @param [Physical::Shipment] shipment The shipment we want to estimate timings for
-      # @param [FriendlyShipping::Services::Ups::TimingOptions] options Options for this call
+      # @param [TimingOptions] options Options for this call
       def timings(shipment, options:, debug: false)
         time_in_transit_request_xml = SerializeTimeInTransitRequest.call(
           shipment: shipment,

lib/friendly_shipping/services/ups/label.rb

@@ -3,16 +3,29 @@
 module FriendlyShipping
   module Services
     class Ups
+      # Represents a label returned by the UPS JAPI.
       class Label < FriendlyShipping::Label
+        # @return [String] the label's USPS tracking number
         attr_reader :usps_tracking_number
 
-        # @param [String] usps_tracking_number The label's usps tracking number. Limited to SUREPOST
+        # @param usps_tracking_number [String] the label's USPS tracking number (only applies to SurePost)
+        # @param kwargs [Hash]
+        # @option kwargs [String] :id the label's unique ID
+        # @option kwargs [String] :shipment_id the label's shipment ID
+        # @option kwargs [String] :tracking_number the label's tracking number
+        # @option kwargs [String] :service_code the label's service code
+        # @option kwargs [String] :label_href the URL for the label
+        # @option kwargs [String] :label_format the label's format
+        # @option kwargs [String] :label_data the raw label data
+        # @option kwargs [Money] :cost the label's cost
+        # @option kwargs [Money] :shipment_cost the overall cost of the shipment
+        # @option kwargs [Hash] :data additional data related to the label
         def initialize(
           usps_tracking_number: nil,
-          **params
+          **kwargs
         )
           @usps_tracking_number = usps_tracking_number
-          super(**params)
+          super(**kwargs)
         end
       end
     end

lib/friendly_shipping/services/ups/label_billing_options.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# TODO stopped here
+
 module FriendlyShipping
   module Services
     class Ups

lib/friendly_shipping/services/ups/label_options.rb

@@ -9,7 +9,7 @@ module Services
     #
     # Required:
     #
-    # @param shipping_method [FriendlyShipping::ShippingMethod] The shipping method to use. We only need the
+    # @param shipping_method [ShippingMethod] The shipping method to use. We only need the
     #   service_code to be set.
     # @param shipper_number [String] account number for the shipper
     #

lib/friendly_shipping/services/ups/rate_estimate_options.rb

@@ -21,7 +21,7 @@ module Services
     # @option pickup_date [Time] UPS pickup date/time. Default: nil
     # @option saturday_delivery [Boolean] should we request Saturday delivery?. Default: false
     # @option saturday_pickup [Boolean] should we request Saturday pickup?. Default: false
-    # @option shipping_method [FriendlyShipping::ShippingMethod] Request rates for a particular shipping method only?
+    # @option shipping_method [ShippingMethod] Request rates for a particular shipping method only?
     #   Default is `nil`, which translates to 'All shipping methods' (The "Shop" option in UPS parlance)
     # @option sub_version [String] The UPS API sub-version to use for requests. Default: 1707
     # @option with_time_in_transit [Boolean] Whether to request timing information alongside the rates

lib/friendly_shipping/services/ups_freight.rb

@@ -60,7 +60,7 @@ def carriers
 
       # Get rates for a shipment
       # @param [Physical::Shipment] shipment The shipment we want to get rates for
-      # @param [FriendlyShipping::Services::UpsFreight::RatesOptions] options Options for obtaining rates for this shipment.
+      # @param [RatesOptions] options Options for obtaining rates for this shipment.
       # @return [Result<ApiResult<Array<Rate>>>] The rates returned from UPS encoded in a
       #   `FriendlyShipping::ApiResult` object.
       def rate_estimates(shipment, options:, debug: false)
@@ -74,7 +74,7 @@ def rate_estimates(shipment, options:, debug: false)
 
       # Get labels for a shipment
       # @param [Physical::Shipment] shipment The shipment we want to get rates for
-      # @param [FriendlyShipping::Services::UpsFreight::LabelOptions] options Options for shipping this shipment.
+      # @param [LabelOptions] options Options for shipping this shipment.
       # @return [Result<ApiResult<ShipmentInformation>] The information that you need for shipping this shipment.
       def labels(shipment, options:, debug: false)
         freight_ship_request_hash = GenerateFreightShipRequestHash.call(shipment: shipment, options: options)

lib/friendly_shipping/services/ups_freight/rates_options.rb

@@ -44,6 +44,11 @@ class RatesOptions < ShipmentOptions
         # @param pickup_request_options [PickupRequestOptions] options for the pickup request
         # @param commodity_information_generator [Callable] a callable that takes a shipment
         #     and an options object to create an Array of commodity fields as per the UPS docs
+        # @param kwargs [Hash]
+        # @option kwargs [Array<StructureOptions>] :structure_options
+        # @option kwargs [Class] :structure_options_class
+        # @option kwargs [Array<PackageOptions>] :package_options
+        # @option kwargs [Class] :package_options_class
         def initialize(
           shipper_number:,
           billing_address:,

lib/friendly_shipping/services/ups_json.rb

@@ -27,7 +27,7 @@
 module FriendlyShipping
   module Services
     class UpsJson
-      include Dry::Monads[:result]
+      include Dry::Monads::Result::Mixin
 
       attr_reader :access_token, :test, :client
 

lib/friendly_shipping/services/ups_json/label.rb

@@ -3,10 +3,23 @@
 module FriendlyShipping
   module Services
     class UpsJson
+      # Represents a label returned by the UPS JSON API.
       class Label < FriendlyShipping::Label
+        # @return [String] the label's USPS tracking number
         attr_reader :usps_tracking_number
 
-        # @param [String] usps_tracking_number The label's usps tracking number. Limited to SUREPOST
+        # @param usps_tracking_number [String] the label's USPS tracking number (only applies to SurePost)
+        # @param kwargs [Hash]
+        # @option kwargs [String] :id the label's unique ID
+        # @option kwargs [String] :shipment_id the label's shipment ID
+        # @option kwargs [String] :tracking_number the label's tracking number
+        # @option kwargs [String] :service_code the label's service code
+        # @option kwargs [String] :label_href the URL for the label
+        # @option kwargs [String] :label_format the label's format
+        # @option kwargs [String] :label_data the raw label data
+        # @option kwargs [Money] :cost the label's cost
+        # @option kwargs [Money] :shipment_cost the overall cost of the shipment
+        # @option kwargs [Hash] :data additional data related to the label
         def initialize(
           usps_tracking_number: nil,
           **kwargs

lib/friendly_shipping/services/ups_json/parse_rate_modifier_hash.rb

@@ -4,7 +4,7 @@ module FriendlyShipping
   module Services
     class UpsJson
       class ParseRateModifierHash
-        # @param [Hash] hash the RateModifier hash from the source JSON
+        # @param [Hash] rate_modifier the RateModifier hash from the source JSON
         # @param [String] currency_code The currency code for this modifier's amount (i.e. 'USD')
         # @return [Hash]
         def self.call(rate_modifier, currency_code:)