Add documentation for mergeable orders finder

Introduce YARD documentation for `Spree::MergeableOrdersFinder` and the
`mergeable_orders_finder_class` configuration attribute to clarify how
order merging behavior can be customized.

This patch adds:

- Detailed YARD docs explaining the purpose and behavior of
  `MergeableOrdersFinder`
- Documentation for the `mergeable_orders_finder_class`

Signed-off-by: Thukten Singye <[email protected]>

Author: ThuktenSingye

core/app/models/spree/mergeable_orders_finder.rb

@@ -1,13 +1,41 @@
 # frozen_string_literal: true
 
 module Spree
+  # Finds orders to merge when a user logs in.
+  #
+  # Configurable via {Spree::Config#mergeable_orders_finder_class}.
+  # Default behavior finds all incomplete orders from the same store.
+  #
+  # @example Custom finder for recent orders only
+  #   class RecentOrdersFinder
+  #     def initialize(user:, store:, current_order:)
+  #       @user = user
+  #       @store = store
+  #       @current_order = current_order
+  #     end
+  #
+  #     def call
+  #       @user.orders.by_store(@store).incomplete
+  #            .where.not(id: @current_order.id)
+  #            .where('created_at > ?', 7.days.ago)
+  #     end
+  #   end
+  #
+  #   Spree::Config.mergeable_orders_finder_class = RecentOrdersFinder
   class MergeableOrdersFinder
+    # @param user [Spree::User] the user whose orders to find
+    # @param store [Spree::Store] the current store
+    # @param current_order [Spree::Order] the current session order
     def initialize(user:, store:, current_order:)
       @user = user
       @store = store
       @current_order = current_order
     end
 
+    # Returns orders that should be merged into the current order
+    #
+    # @return [ActiveRecord::Relation<Spree::Order>] incomplete orders from the
+    # same store
     def call
       @user.orders.by_store(@store).incomplete.where.not(id: @current_order.id)
     end

core/lib/spree/app_configuration.rb

@@ -409,6 +409,11 @@ def default_pricing_options
     #   as Spree::OrderMerger.
     class_name_attribute :order_merger_class, default: 'Spree::OrderMerger'
 
+    # Allows providing your own class for selecting which orders to merge.
+    #
+    # @!attribute [rw] mergeable_orders_finder_class
+    # @return [Class] a class with the same public interfaces as
+    #   Spree::MergeableOrdersFinder.
     class_name_attribute :mergeable_orders_finder_class, default: 'Spree::MergeableOrdersFinder'
 
     # Allows providing your own class for adding default payments to a user's