Move UNION_COLLECTION_NAMES out of the parser entirely

The parser's node-class selection for <...> still referenced
UNION_COLLECTION_NAMES to choose between CollectionType and
ParameterizedType, even after slot_pipe stopped depending on it. Per
review, that's still type-specific knowledge living in parsing code.

Merge ParameterizedType into CollectionType: the parser now always
builds a CollectionType for <...> (aside from the pre-existing Hash<K,
V> and fixed-tuple special cases), and CollectionType#to_s decides
per-instance, via a private #union? check, whether to render its type
parameters as a flat union (Array/Set, or any single parameter) or
neutrally. UNION_COLLECTION_NAMES now lives only on CollectionType,
read only during rendering.

Output is unchanged for every existing case.

Author: apiology

lib/yard/tags/types_explainer.rb

@@ -123,20 +123,48 @@ def disambiguate(type, singular)
       end
 
       # @private
+      #
+      # `<...>`'s type parameters are conventionally used two ways - as a
+      # homogeneous collection's implicit union of element type(s), or as
+      # a class's distinct, positional type parameters, e.g.
+      # `Result<Success, Failure>` - and this class renders either way,
+      # chosen per instance by {#union?}. This keeps that choice entirely
+      # out of the parser: every `<...>` becomes one of these, regardless
+      # of name.
       class CollectionType < Type
         attr_accessor :types
 
+        # Type names known in advance to be genuinely homogeneous
+        # collections, where `<...>`'s type parameters really do mean
+        # "any one of these". Fixed and not user-configurable - YARD has
+        # no syntax for a class to declare its own `<...>` convention, so
+        # this can only ever be a hardcoded, conservative list.
+        UNION_COLLECTION_NAMES = %w[Array Set].freeze
+
         def initialize(name, types)
           @name = name
           @types = types
         end
 
         def to_s(_singular = true)
-          "#{indefinite_article(name)} #{name} of (" + list_join(flattened_types.map {|t| t.to_s(false) }) + ")"
+          if union?
+            "#{indefinite_article(name)} #{name} of (" + list_join(flattened_types.map {|t| t.to_s(false) }) + ")"
+          else
+            "#{indefinite_article(name)} #{name} with type parameters (" +
+              types.map {|t| t.to_s(true) }.join(", ") + ")"
+          end
         end
 
         private
 
+        # A single type parameter is never ambiguous (there's nothing to
+        # distinguish a union from a positional type parameter when
+        # there's only one), so it's read as a union regardless of name;
+        # otherwise, only the known homogeneous-collection names are.
+        def union?
+          types.size <= 1 || UNION_COLLECTION_NAMES.include?(name)
+        end
+
         # A parsed type parameter that's itself a union (from `Foo | Bar`
         # in e.g. `Array<Foo | Bar, Baz>`) is a {GroupType}. Since this
         # whole parameter list is already read as one flat union, absorb
@@ -148,29 +176,6 @@ def flattened_types
         end
       end
 
-      # @private
-      #
-      # Unlike {CollectionType}, this doesn't assert that its type
-      # parameters are alternatives ("of (A's or B's)") - `<...>` is
-      # conventionally used both ways (a homogeneous collection's element
-      # type(s), or a class's distinct positional type-parameter roles,
-      # e.g. `Result<Success, Failure>`), and there's no way for YARD to
-      # know which one a given class means. This is the honest fallback
-      # for any name not specifically known to mean the former.
-      class ParameterizedType < Type
-        attr_accessor :types
-
-        def initialize(name, types)
-          @name = name
-          @types = types
-        end
-
-        def to_s(_singular = true)
-          "#{indefinite_article(name)} #{name} with type parameters (" +
-            types.map {|t| t.to_s(true) }.join(", ") + ")"
-        end
-      end
-
       # @private
       class FixedCollectionType < CollectionType
         def to_s(_singular = true)
@@ -258,13 +263,6 @@ class Parser
           :parse_end => nil
         }
 
-        # Type names known in advance to be genuinely homogeneous
-        # collections, where `<...>`'s comma-separated slots really do mean
-        # "any one of these". Fixed and not user-configurable - YARD has no
-        # syntax for a class to declare its own `<...>` convention, so this
-        # can only ever be a hardcoded, conservative list.
-        UNION_COLLECTION_NAMES = %w[Array Set].freeze
-
         def self.parse(string)
           new(string).parse
         end
@@ -377,18 +375,12 @@ def parse_until(until_tokens, slot_pipe: false)
                 # (slot 0 = key type, slot 1 = value type), matching the
                 # dedicated `Hash{K=>V}` syntax - not an implicit union.
                 HashCollectionType.new(name, [nested_types[0]], [nested_types[1]])
-              elsif nested_types.size <= 1 || UNION_COLLECTION_NAMES.include?(name)
-                # A single slot is never ambiguous (nothing to distinguish
-                # union from positional with only one type), and these
-                # names are known, genuinely homogeneous collections.
-                CollectionType.new(name, nested_types)
               else
-                # `<...>` is conventionally used both ways - a homogeneous
-                # collection's element type(s), or a class's distinct
-                # positional type-parameter roles - and YARD has no way to
-                # know which one an arbitrary class means. Don't assert
-                # union for a name we don't specifically know means that.
-                ParameterizedType.new(name, nested_types)
+                # Whether these type parameters get described as a union
+                # (Array, Set) or neutrally (everything else) doesn't
+                # affect parsing, so it's not decided here - see
+                # {CollectionType#union?}.
+                CollectionType.new(name, nested_types)
               end
             when :group_start
               raise SyntaxError, "'[' cannot follow a type name" if name

spec/tags/types_explainer_spec.rb

@@ -149,12 +149,10 @@ def type(name)
       @t.types = [group, type("Baz")]
       expect(@t.to_s).to eq "an Array of (Foos, Bars or Bazs)"
     end
-  end
 
-  describe YARD::Tags::TypesExplainer::ParameterizedType, '#to_s' do
-    it "lists type parameters without pluralizing or asserting union/order" do
-      parameterized = described_class.new("Result", [type("Success"), type("Failure")])
-      expect(parameterized.to_s).to eq "a Result with type parameters (a Success, a Failure)"
+    it "lists a non-allow-listed name's 2+ type parameters without pluralizing or asserting union/order" do
+      result = described_class.new("Result", [type("Success"), type("Failure")])
+      expect(result.to_s).to eq "a Result with type parameters (a Success, a Failure)"
     end
   end
 
@@ -262,11 +260,12 @@ def parse_fail(types)
       expect(type.first).to be_a(YARD::Tags::TypesExplainer::CollectionType)
     end
 
-    it "uses ParameterizedType for a non-allow-listed name with 2+ parameters" do
+    it "renders a non-allow-listed name's 2+ parameters neutrally" do
       type = parse("Result<Success, Failure>")
-      expect(type.first).to be_a(YARD::Tags::TypesExplainer::ParameterizedType)
+      expect(type.first).to be_a(YARD::Tags::TypesExplainer::CollectionType)
       expect(type.first.name).to eq "Result"
       expect(type.first.types.map(&:name)).to eq ["Success", "Failure"]
+      expect(type.first.to_s).to eq "a Result with type parameters (a Success, a Failure)"
     end
 
     it "special-cases Hash<KeyType, ValueType> to match Hash{K=>V}'s key/value rendering" do
@@ -277,16 +276,18 @@ def parse_fail(types)
       expect(by_angle_brackets.first.value_types.map(&:name)).to eq by_braces.first.value_types.map(&:name)
     end
 
-    it "falls back to ParameterizedType for Hash<...> with the wrong number of parameters" do
+    it "falls back to a neutral CollectionType for Hash<...> with the wrong number of parameters" do
       type = parse("Hash<A, B, C>")
-      expect(type.first).to be_a(YARD::Tags::TypesExplainer::ParameterizedType)
+      expect(type.first).to be_a(YARD::Tags::TypesExplainer::CollectionType)
+      expect(type.first.to_s).to eq "a Hash with type parameters (an A, a B, a C)"
       type = parse("Hash<A>")
       expect(type.first).to be_a(YARD::Tags::TypesExplainer::CollectionType)
+      expect(type.first.to_s).to eq "a Hash of (A's)"
     end
 
     it "groups '|' within a single slot of a non-allow-listed <...>, since its slots are positional" do
       type = parse("Result<Success | Failure, Other>")
-      expect(type.first).to be_a(YARD::Tags::TypesExplainer::ParameterizedType)
+      expect(type.first).to be_a(YARD::Tags::TypesExplainer::CollectionType)
       expect(type.first.types.size).to eq 2
       expect(type.first.types.first).to be_a(YARD::Tags::TypesExplainer::GroupType)
       expect(type.first.types.first.types.map(&:name)).to eq ["Success", "Failure"]