From 3191ca961670737237370f7a2603ffeb5d08b29c Mon Sep 17 00:00:00 2001 From: Matthew Bass Date: Mon, 1 Jan 2024 10:34:49 -0500 Subject: [PATCH 1/3] Add YARD docs to UPS classes --- lib/friendly_shipping/services/ups.rb | 4 ++-- lib/friendly_shipping/services/ups/label.rb | 19 ++++++++++++++++--- .../services/ups/label_billing_options.rb | 2 ++ .../services/ups/label_options.rb | 2 +- .../services/ups/rate_estimate_options.rb | 2 +- 5 files changed, 22 insertions(+), 7 deletions(-) diff --git a/lib/friendly_shipping/services/ups.rb b/lib/friendly_shipping/services/ups.rb index 86018c51..48c8e02a 100644 --- a/lib/friendly_shipping/services/ups.rb +++ b/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>>] 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, diff --git a/lib/friendly_shipping/services/ups/label.rb b/lib/friendly_shipping/services/ups/label.rb index e11e0143..0efd90c9 100644 --- a/lib/friendly_shipping/services/ups/label.rb +++ b/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 diff --git a/lib/friendly_shipping/services/ups/label_billing_options.rb b/lib/friendly_shipping/services/ups/label_billing_options.rb index b83bb8cf..d978b47c 100644 --- a/lib/friendly_shipping/services/ups/label_billing_options.rb +++ b/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 diff --git a/lib/friendly_shipping/services/ups/label_options.rb b/lib/friendly_shipping/services/ups/label_options.rb index e32a9fb6..abba1cea 100644 --- a/lib/friendly_shipping/services/ups/label_options.rb +++ b/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 # diff --git a/lib/friendly_shipping/services/ups/rate_estimate_options.rb b/lib/friendly_shipping/services/ups/rate_estimate_options.rb index 14e8eca2..62d3be82 100644 --- a/lib/friendly_shipping/services/ups/rate_estimate_options.rb +++ b/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 From 8ccffb1278599894216160f54c1fae8a7efd24dd Mon Sep 17 00:00:00 2001 From: Matthew Bass Date: Thu, 15 Feb 2024 12:36:49 -0500 Subject: [PATCH 2/3] Add YARD docs to UPS JSON classes --- lib/friendly_shipping/services/ups_json.rb | 2 +- lib/friendly_shipping/services/ups_json/label.rb | 15 ++++++++++++++- .../services/ups_json/parse_rate_modifier_hash.rb | 2 +- 3 files changed, 16 insertions(+), 3 deletions(-) diff --git a/lib/friendly_shipping/services/ups_json.rb b/lib/friendly_shipping/services/ups_json.rb index ce4bb808..c2b1fe1d 100644 --- a/lib/friendly_shipping/services/ups_json.rb +++ b/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 diff --git a/lib/friendly_shipping/services/ups_json/label.rb b/lib/friendly_shipping/services/ups_json/label.rb index bc88b35d..d4645beb 100644 --- a/lib/friendly_shipping/services/ups_json/label.rb +++ b/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 diff --git a/lib/friendly_shipping/services/ups_json/parse_rate_modifier_hash.rb b/lib/friendly_shipping/services/ups_json/parse_rate_modifier_hash.rb index dd6d264c..19f0459a 100644 --- a/lib/friendly_shipping/services/ups_json/parse_rate_modifier_hash.rb +++ b/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:) From 260f8f89ea5876fc4571c472d303254530749d72 Mon Sep 17 00:00:00 2001 From: Matthew Bass Date: Mon, 1 Jan 2024 10:35:01 -0500 Subject: [PATCH 3/3] Add YARD docs to UPS Freight classes --- lib/friendly_shipping/services/ups_freight.rb | 4 ++-- lib/friendly_shipping/services/ups_freight/rates_options.rb | 5 +++++ 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/lib/friendly_shipping/services/ups_freight.rb b/lib/friendly_shipping/services/ups_freight.rb index 7b5947d0..1eb3ee25 100644 --- a/lib/friendly_shipping/services/ups_freight.rb +++ b/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>>] 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] 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) diff --git a/lib/friendly_shipping/services/ups_freight/rates_options.rb b/lib/friendly_shipping/services/ups_freight/rates_options.rb index 8ac01e55..4fbfe6a6 100644 --- a/lib/friendly_shipping/services/ups_freight/rates_options.rb +++ b/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] :structure_options + # @option kwargs [Class] :structure_options_class + # @option kwargs [Array] :package_options + # @option kwargs [Class] :package_options_class def initialize( shipper_number:, billing_address:,