Clarify validator-shape comments

Author: numbata

lib/grape-swagger/request_param_parsers/route.rb

@@ -50,6 +50,8 @@ def fetch_inherited_params(stackable_values)
 
       # Grape 3.2+ serializes `type: [A, B]` via VariantCollectionCoercer#to_s, losing the type list.
       # Recover it from the matching CoerceValidator entry in stackable_values[:validations].
+      # Grape 3.2+ stores validator metadata as Hash entries; older supported versions use
+      # CoerceValidator object instances and require private-ivar reads below.
       # If the internal structure changes in a future Grape version this silently returns {}.
       def collect_variant_types(stackable_values)
         variant_types = {}

spec/swagger_v2/param_multi_type_spec.rb

@@ -112,7 +112,9 @@ def app
   end
 
   # Canary tests for Grape internals used by collect_variant_types.
-  # Fails after a Grape upgrade? Update collect_variant_types private-ivar reads.
+  # Fails after a Grape upgrade? Update collect_variant_types to match the new
+  # validator shape. Grape 3.2+: Hash entries (key lookups). Older supported
+  # versions: object instances (private-ivar reads).
   describe 'Grape internal contract for collect_variant_types' do
     before { skip unless defined?(Grape::Validations::Types::VariantCollectionCoercer) }
 
@@ -147,7 +149,7 @@ def app
         expect(coerce_validator).not_to be_nil
       end
 
-      it 'recovers types from the Hash-shaped validator path' do
+      it 'processes a Hash-shaped validator entry (unit test of entry-parsing logic)' do
         scope = Struct.new(:name) do
           def full_name(attr)
             attr.to_s
@@ -198,6 +200,7 @@ def app
     end
 
     it 'uses the last-declared type' do
+      # Relies on validators being iterated in declaration order; last write wins.
       types = subject.to_h { |p| [p['name'], p['type']] }
       expect(types['n']).to eq('string')
     end