chore: improve yard docs readability (#197)

Author: stainless-app[bot]

lib/orb/resources/alerts.rb

@@ -5,11 +5,10 @@ module Resources
     class Alerts
       # This endpoint retrieves an alert by its ID.
       #
-      # @param alert_id [String]
-      #
-      # @param params [Orb::Models::AlertRetrieveParams, Hash{Symbol=>Object}] .
+      # @overload retrieve(alert_id, request_options: {})
       #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param alert_id [String]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Models::Alert]
       #
@@ -25,13 +24,11 @@ def retrieve(alert_id, params = {})
 
       # This endpoint updates the thresholds of an alert.
       #
-      # @param alert_configuration_id [String]
-      #
-      # @param params [Orb::Models::AlertUpdateParams, Hash{Symbol=>Object}] .
-      #
-      #   @option params [Array<Orb::Models::AlertUpdateParams::Threshold>] :thresholds The thresholds that define the values at which the alert will be triggered.
+      # @overload update(alert_configuration_id, thresholds:, request_options: {})
       #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param alert_configuration_id [String]
+      # @param thresholds [Array<Orb::Models::AlertUpdateParams::Threshold>]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Models::Alert]
       #
@@ -59,28 +56,18 @@ def update(alert_configuration_id, params)
       #   This endpoint follows Orb's
       #   [standardized pagination format](/api-reference/pagination).
       #
-      # @param params [Orb::Models::AlertListParams, Hash{Symbol=>Object}] .
-      #
-      #   @option params [Time, nil] :created_at_gt
-      #
-      #   @option params [Time, nil] :created_at_gte
-      #
-      #   @option params [Time, nil] :created_at_lt
-      #
-      #   @option params [Time, nil] :created_at_lte
+      # @overload list(created_at_gt: nil, created_at_gte: nil, created_at_lt: nil, created_at_lte: nil, cursor: nil, customer_id: nil, external_customer_id: nil, limit: nil, subscription_id: nil, request_options: {})
       #
-      #   @option params [String, nil] :cursor Cursor for pagination. This can be populated by the `next_cursor` value returned
-      #     from the initial request.
-      #
-      #   @option params [String, nil] :customer_id Fetch alerts scoped to this customer_id
-      #
-      #   @option params [String, nil] :external_customer_id Fetch alerts scoped to this external_customer_id
-      #
-      #   @option params [Integer] :limit The number of items to fetch. Defaults to 20.
-      #
-      #   @option params [String, nil] :subscription_id Fetch alerts scoped to this subscription_id
-      #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param created_at_gt [Time, nil]
+      # @param created_at_gte [Time, nil]
+      # @param created_at_lt [Time, nil]
+      # @param created_at_lte [Time, nil]
+      # @param cursor [String, nil]
+      # @param customer_id [String, nil]
+      # @param external_customer_id [String, nil]
+      # @param limit [Integer]
+      # @param subscription_id [String, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Page<Orb::Models::Alert>]
       #
@@ -106,17 +93,13 @@ def list(params = {})
       #   while `credit_balance_depleted` and `credit_balance_recovered` alerts do not
       #   require thresholds.
       #
-      # @param customer_id [String]
-      #
-      # @param params [Orb::Models::AlertCreateForCustomerParams, Hash{Symbol=>Object}] .
-      #
-      #   @option params [String] :currency The case sensitive currency or custom pricing unit to use for this alert.
-      #
-      #   @option params [Symbol, Orb::Models::AlertCreateForCustomerParams::Type] :type The type of alert to create. This must be a valid alert type.
-      #
-      #   @option params [Array<Orb::Models::AlertCreateForCustomerParams::Threshold>, nil] :thresholds The thresholds that define the values at which the alert will be triggered.
+      # @overload create_for_customer(customer_id, currency:, type:, thresholds: nil, request_options: {})
       #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param customer_id [String]
+      # @param currency [String]
+      # @param type [Symbol, Orb::Models::AlertCreateForCustomerParams::Type]
+      # @param thresholds [Array<Orb::Models::AlertCreateForCustomerParams::Threshold>, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Models::Alert]
       #
@@ -141,17 +124,13 @@ def create_for_customer(customer_id, params)
       #   while `credit_balance_depleted` and `credit_balance_recovered` alerts do not
       #   require thresholds.
       #
-      # @param external_customer_id [String]
-      #
-      # @param params [Orb::Models::AlertCreateForExternalCustomerParams, Hash{Symbol=>Object}] .
-      #
-      #   @option params [String] :currency The case sensitive currency or custom pricing unit to use for this alert.
-      #
-      #   @option params [Symbol, Orb::Models::AlertCreateForExternalCustomerParams::Type] :type The type of alert to create. This must be a valid alert type.
-      #
-      #   @option params [Array<Orb::Models::AlertCreateForExternalCustomerParams::Threshold>, nil] :thresholds The thresholds that define the values at which the alert will be triggered.
+      # @overload create_for_external_customer(external_customer_id, currency:, type:, thresholds: nil, request_options: {})
       #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param external_customer_id [String]
+      # @param currency [String]
+      # @param type [Symbol, Orb::Models::AlertCreateForExternalCustomerParams::Type]
+      # @param thresholds [Array<Orb::Models::AlertCreateForExternalCustomerParams::Threshold>, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Models::Alert]
       #
@@ -179,17 +158,13 @@ def create_for_external_customer(external_customer_id, params)
       #   per metric that is a part of the subscription. Alerts are triggered based on
       #   usage or cost conditions met during the current billing cycle.
       #
-      # @param subscription_id [String]
-      #
-      # @param params [Orb::Models::AlertCreateForSubscriptionParams, Hash{Symbol=>Object}] .
-      #
-      #   @option params [Array<Orb::Models::AlertCreateForSubscriptionParams::Threshold>] :thresholds The thresholds that define the values at which the alert will be triggered.
-      #
-      #   @option params [Symbol, Orb::Models::AlertCreateForSubscriptionParams::Type] :type The type of alert to create. This must be a valid alert type.
+      # @overload create_for_subscription(subscription_id, thresholds:, type:, metric_id: nil, request_options: {})
       #
-      #   @option params [String, nil] :metric_id The metric to track usage for.
-      #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param subscription_id [String]
+      # @param thresholds [Array<Orb::Models::AlertCreateForSubscriptionParams::Threshold>]
+      # @param type [Symbol, Orb::Models::AlertCreateForSubscriptionParams::Type]
+      # @param metric_id [String, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Models::Alert]
       #
@@ -209,13 +184,11 @@ def create_for_subscription(subscription_id, params)
       #   a specific subscription, you must include the `subscription_id`. The
       #   `subscription_id` is not required for customer or subscription level alerts.
       #
-      # @param alert_configuration_id [String]
-      #
-      # @param params [Orb::Models::AlertDisableParams, Hash{Symbol=>Object}] .
-      #
-      #   @option params [String, nil] :subscription_id Used to update the status of a plan alert scoped to this subscription_id
+      # @overload disable(alert_configuration_id, subscription_id: nil, request_options: {})
       #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param alert_configuration_id [String]
+      # @param subscription_id [String, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Models::Alert]
       #
@@ -235,13 +208,11 @@ def disable(alert_configuration_id, params = {})
       #   specific subscription, you must include the `subscription_id`. The
       #   `subscription_id` is not required for customer or subscription level alerts.
       #
-      # @param alert_configuration_id [String]
-      #
-      # @param params [Orb::Models::AlertEnableParams, Hash{Symbol=>Object}] .
+      # @overload enable(alert_configuration_id, subscription_id: nil, request_options: {})
       #
-      #   @option params [String, nil] :subscription_id Used to update the status of a plan alert scoped to this subscription_id
-      #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param alert_configuration_id [String]
+      # @param subscription_id [String, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Models::Alert]
       #

lib/orb/resources/coupons.rb

@@ -9,19 +9,13 @@ class Coupons
       # This endpoint allows the creation of coupons, which can then be redeemed at
       #   subscription creation or plan change.
       #
-      # @param params [Orb::Models::CouponCreateParams, Hash{Symbol=>Object}] .
+      # @overload create(discount:, redemption_code:, duration_in_months: nil, max_redemptions: nil, request_options: {})
       #
-      #   @option params [Orb::Models::CouponCreateParams::Discount::NewCouponPercentageDiscount, Orb::Models::CouponCreateParams::Discount::NewCouponAmountDiscount] :discount
-      #
-      #   @option params [String] :redemption_code This string can be used to redeem this coupon for a given subscription.
-      #
-      #   @option params [Integer, nil] :duration_in_months This allows for a coupon's discount to apply for a limited time (determined in
-      #     months); a `null` value here means "unlimited time".
-      #
-      #   @option params [Integer, nil] :max_redemptions The maximum number of redemptions allowed for this coupon before it is
-      #     exhausted;`null` here means "unlimited".
-      #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param discount [Orb::Models::CouponCreateParams::Discount::NewCouponPercentageDiscount, Orb::Models::CouponCreateParams::Discount::NewCouponAmountDiscount]
+      # @param redemption_code [String]
+      # @param duration_in_months [Integer, nil]
+      # @param max_redemptions [Integer, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Models::Coupon]
       #
@@ -44,19 +38,13 @@ def create(params)
       #   the next page of results if they exist. More information about pagination can be
       #   found in the Pagination-metadata schema.
       #
-      # @param params [Orb::Models::CouponListParams, Hash{Symbol=>Object}] .
-      #
-      #   @option params [String, nil] :cursor Cursor for pagination. This can be populated by the `next_cursor` value returned
-      #     from the initial request.
-      #
-      #   @option params [Integer] :limit The number of items to fetch. Defaults to 20.
-      #
-      #   @option params [String, nil] :redemption_code Filter to coupons matching this redemption code.
+      # @overload list(cursor: nil, limit: nil, redemption_code: nil, show_archived: nil, request_options: {})
       #
-      #   @option params [Boolean, nil] :show_archived Show archived coupons as well (by default, this endpoint only returns active
-      #     coupons).
-      #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param cursor [String, nil]
+      # @param limit [Integer]
+      # @param redemption_code [String, nil]
+      # @param show_archived [Boolean, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Page<Orb::Models::Coupon>]
       #
@@ -77,11 +65,10 @@ def list(params = {})
       #   redeemed, and will be hidden from lists of active coupons. Additionally, once a
       #   coupon is archived, its redemption code can be reused for a different coupon.
       #
-      # @param coupon_id [String]
-      #
-      # @param params [Orb::Models::CouponArchiveParams, Hash{Symbol=>Object}] .
+      # @overload archive(coupon_id, request_options: {})
       #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param coupon_id [String]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Models::Coupon]
       #
@@ -99,11 +86,10 @@ def archive(coupon_id, params = {})
       #   code, use the [List coupons](list-coupons) endpoint with the redemption_code
       #   parameter.
       #
-      # @param coupon_id [String]
-      #
-      # @param params [Orb::Models::CouponFetchParams, Hash{Symbol=>Object}] .
+      # @overload fetch(coupon_id, request_options: {})
       #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param coupon_id [String]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Models::Coupon]
       #

lib/orb/resources/coupons/subscriptions.rb

@@ -9,16 +9,12 @@ class Subscriptions
         #   the most recently created subscription. For a full discussion of the
         #   subscription resource, see [Subscription](/core-concepts#subscription).
         #
-        # @param coupon_id [String]
-        #
-        # @param params [Orb::Models::Coupons::SubscriptionListParams, Hash{Symbol=>Object}] .
-        #
-        #   @option params [String, nil] :cursor Cursor for pagination. This can be populated by the `next_cursor` value returned
-        #     from the initial request.
+        # @overload list(coupon_id, cursor: nil, limit: nil, request_options: {})
         #
-        #   @option params [Integer] :limit The number of items to fetch. Defaults to 20.
-        #
-        #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        # @param coupon_id [String]
+        # @param cursor [String, nil]
+        # @param limit [Integer]
+        # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [Orb::Page<Orb::Models::Subscription>]
         #

lib/orb/resources/credit_notes.rb

@@ -6,15 +6,12 @@ class CreditNotes
       # This endpoint is used to create a single
       #   [`Credit Note`](/invoicing/credit-notes).
       #
-      # @param params [Orb::Models::CreditNoteCreateParams, Hash{Symbol=>Object}] .
+      # @overload create(line_items:, memo: nil, reason: nil, request_options: {})
       #
-      #   @option params [Array<Orb::Models::CreditNoteCreateParams::LineItem>] :line_items
-      #
-      #   @option params [String, nil] :memo An optional memo to attach to the credit note.
-      #
-      #   @option params [Symbol, Orb::Models::CreditNoteCreateParams::Reason, nil] :reason An optional reason for the credit note.
-      #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param line_items [Array<Orb::Models::CreditNoteCreateParams::LineItem>]
+      # @param memo [String, nil]
+      # @param reason [Symbol, Orb::Models::CreditNoteCreateParams::Reason, nil]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Models::CreditNote]
       #
@@ -34,22 +31,15 @@ def create(params)
       #   subscription_id, or external_customer_id. The credit notes will be returned in
       #   reverse chronological order by `creation_time`.
       #
-      # @param params [Orb::Models::CreditNoteListParams, Hash{Symbol=>Object}] .
-      #
-      #   @option params [Time, nil] :created_at_gt
-      #
-      #   @option params [Time, nil] :created_at_gte
-      #
-      #   @option params [Time, nil] :created_at_lt
+      # @overload list(created_at_gt: nil, created_at_gte: nil, created_at_lt: nil, created_at_lte: nil, cursor: nil, limit: nil, request_options: {})
       #
-      #   @option params [Time, nil] :created_at_lte
-      #
-      #   @option params [String, nil] :cursor Cursor for pagination. This can be populated by the `next_cursor` value returned
-      #     from the initial request.
-      #
-      #   @option params [Integer] :limit The number of items to fetch. Defaults to 20.
-      #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param created_at_gt [Time, nil]
+      # @param created_at_gte [Time, nil]
+      # @param created_at_lt [Time, nil]
+      # @param created_at_lte [Time, nil]
+      # @param cursor [String, nil]
+      # @param limit [Integer]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Page<Orb::Models::CreditNote>]
       #
@@ -69,11 +59,10 @@ def list(params = {})
       # This endpoint is used to fetch a single [`Credit Note`](/invoicing/credit-notes)
       #   given an identifier.
       #
-      # @param credit_note_id [String]
-      #
-      # @param params [Orb::Models::CreditNoteFetchParams, Hash{Symbol=>Object}] .
+      # @overload fetch(credit_note_id, request_options: {})
       #
-      #   @option params [Orb::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      # @param credit_note_id [String]
+      # @param request_options [Orb::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Orb::Models::CreditNote]
       #