docs: Add documentation for RoutingTagMethods module

app/forms/batch_update_form/base.rb

@@ -115,6 +115,7 @@ def form_data_boolean(_attribute_name, _options)
       [%w[Yes true], %w[No false]]
     end
 
+    # @param attribute_name [Symbol] The name of the attribute.
     # @param options [Hash]
     #   :class_name [String] required.
     #   :display_name [Symbol] default :name.
@@ -130,8 +131,7 @@ def form_data_foreign_key(_attribute_name, options = {})
       scope = klass.all
       scope = scope.public_send(custom_scope) if custom_scope.is_a?(Symbol)
       scope = custom_scope.call(scope) if custom_scope.is_a?(Proc)
-      result = scope.pluck(display_name, primary_key)
-      result
+      scope.pluck(display_name, primary_key)
     end
 
     def form_data_integer_collection(_attribute_name, options)

app/forms/batch_update_form/routing_tag_methods.rb

@@ -1,8 +1,29 @@
 # frozen_string_literal: true
 
+# Module containing methods related to routing tags for batch update forms.
+# This module is designed to be extended by classes needing to handle routing tag
+# attributes, specifically the `routing_tag_ids` attribute, which allows for
+# selecting multiple routing tags or an "Any tag" option.
+#
+# example:
+#   class BatchUpdateForm::Some < Base
+#    include BatchUpdateForm::RoutingTagMethods
+#
+#    attribute :routing_tag_ids, type: :foreign_key, class_name: 'Routing::RoutingTag', any_tag: true
+#   end
 module BatchUpdateForm::RoutingTagMethods
   extend ActiveSupport::Concern
 
+  # Class methods for handling routing tag attributes.
+
+  # Overrides the base form's `form_data_foreign_key` method to handle
+  # the special case of `routing_tag_ids`.  This method adds the "Any tag"
+  # option to the list of available routing tags.
+  #
+  # @param attribute_name [Symbol] The name of the attribute (should be :routing_tag_ids).
+  # @param options [Hash] Options for the foreign key attribute.  Must include :any_tag boolean.
+  # @return [Array<Array(2)>] An array of arrays, where each inner array contains
+  #   [display_name, primary_key] for each routing tag.  Includes "Any tag" if :any_tag is true.
   class_methods do
     def form_data_foreign_key(attribute_name, options = {})
       return super(attribute_name, options) unless attribute_name == :routing_tag_ids
@@ -16,6 +37,11 @@ def form_data_foreign_key(attribute_name, options = {})
       scope
     end
 
+    # Adds the "Any tag" option to the beginning of the provided scope.
+    #
+    # @param scope [Array<Array(2)>] An array of arrays representing the routing tags.
+    # @param options [Hash] Options for the foreign key attribute.  Must include :any_tag boolean.
+    # @return [Array<Array(2)>] The scope with the "Any tag" option prepended.
     def add_any_tag_option(scope, options)
       if options[:any_tag] == true
         scope.prepend([[Routing::RoutingTag::ANY_TAG]])