Suggest the minimal type disambiguation when an overload doesn't have any unique types

Package.resolved

@@ -1,5 +1,14 @@
 {
   "pins" : [
+    {
+      "identity" : "swift-algorithms",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-algorithms",
+      "state" : {
+        "revision" : "f6919dfc309e7f1b56224378b11e28bab5bccc42",
+        "version" : "1.2.0"
+      }
+    },
     {
       "identity" : "swift-argument-parser",
       "kind" : "remoteSourceControl",
@@ -90,6 +99,15 @@
         "version" : "2.68.0"
       }
     },
+    {
+      "identity" : "swift-numerics",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-numerics.git",
+      "state" : {
+        "revision" : "0a5bc04095a675662cf24757cc0640aa2204253b",
+        "version" : "1.0.2"
+      }
+    },
     {
       "identity" : "swift-system",
       "kind" : "remoteSourceControl",

Package.swift

@@ -41,6 +41,7 @@ let package = Package(
                 .product(name: "SymbolKit", package: "swift-docc-symbolkit"),
                 .product(name: "CLMDB", package: "swift-lmdb"),
                 .product(name: "Crypto", package: "swift-crypto"),
+                .product(name: "Algorithms", package: "swift-algorithms"),
             ],
             swiftSettings: swiftSettings
         ),
@@ -136,6 +137,7 @@ if ProcessInfo.processInfo.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil {
         .package(url: "https://github.com/apple/swift-docc-symbolkit", branch: "main"),
         .package(url: "https://github.com/apple/swift-crypto.git", from: "2.5.0"),
         .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.2.0"),
+        .package(url: "https://github.com/apple/swift-algorithms", from: "1.2.0"),
     ]
 } else {
     // Building in the Swift.org CI system, so rely on local versions of dependencies.
@@ -146,5 +148,6 @@ if ProcessInfo.processInfo.environment["SWIFTCI_USE_LOCAL_DEPS"] == nil {
         .package(path: "../swift-argument-parser"),
         .package(path: "../swift-docc-symbolkit"),
         .package(path: "../swift-crypto"),
+        .package(path: "../swift-algorithms"),
     ]
 }

Sources/SwiftDocC/Infrastructure/Link Resolution/PathHierarchy+DisambiguatedPaths.swift

@@ -189,7 +189,7 @@ extension PathHierarchy {
 extension PathHierarchy.DisambiguationContainer {
 
     static func disambiguatedValues(
-        for elements: some Sequence<Element>,
+        for elements: some Collection<Element>,
         includeLanguage: Bool = false,
         allowAdvancedDisambiguation: Bool = true
     ) -> [(value: PathHierarchy.Node, disambiguation: Disambiguation)] {
@@ -203,13 +203,20 @@ extension PathHierarchy.DisambiguationContainer {
     }
 
     private static func _disambiguatedValues(
-        for elements: some Sequence<Element>,
+        for elements: some Collection<Element>,
         includeLanguage: Bool,
         allowAdvancedDisambiguation: Bool
     ) -> [(value: PathHierarchy.Node, disambiguation: Disambiguation)] {
         var collisions: [(value: PathHierarchy.Node, disambiguation: Disambiguation)] = []
+        // Assume that all elements will find a disambiguation (or close to it)
+        collisions.reserveCapacity(elements.count)
 
-        var remainingIDs = Set(elements.map(\.node.identifier))
+        var remainingIDs = Set<ResolvedIdentifier>()
+        remainingIDs.reserveCapacity(elements.count)
+        for element in elements {
+            guard let id = element.node.identifier else { continue }
+            remainingIDs.insert(id)
+        }
 
         // Kind disambiguation is the most readable, so we start by checking if any element has a unique kind.
         let groupedByKind = [String?: [Element]](grouping: elements, by: \.kind)
@@ -233,7 +240,7 @@ extension PathHierarchy.DisambiguationContainer {
             collisions += _disambiguateByTypeSignature(
                 elementsThatSupportAdvancedDisambiguation,
                 types: \.returnTypes,
-                makeDisambiguation: Disambiguation.returnTypes,
+                makeDisambiguation: { .returnTypes($1) },
                 remainingIDs: &remainingIDs
             )
             if remainingIDs.isEmpty {
@@ -243,7 +250,20 @@ extension PathHierarchy.DisambiguationContainer {
             collisions += _disambiguateByTypeSignature(
                 elementsThatSupportAdvancedDisambiguation,
                 types: \.parameterTypes,
-                makeDisambiguation: Disambiguation.parameterTypes,
+                makeDisambiguation: { .parameterTypes($1) },
+                remainingIDs: &remainingIDs
+            )
+            if remainingIDs.isEmpty {
+                return collisions
+            }
+
+            collisions += _disambiguateByTypeSignature(
+                elementsThatSupportAdvancedDisambiguation,
+                types: { ($0.parameterTypes ?? []) + ($0.returnTypes ?? []) },
+                makeDisambiguation: {
+                    let numberOfReturnTypes = $0.returnTypes?.count ?? 0
+                    return .mixedTypes(parameterTypes: $1.dropLast(numberOfReturnTypes), returnTypes: $1.suffix(numberOfReturnTypes))
+                },
                 remainingIDs: &remainingIDs
             )
             if remainingIDs.isEmpty {
@@ -341,6 +361,8 @@ extension PathHierarchy.DisambiguationContainer {
         case parameterTypes([String])
         /// This node is disambiguated by its return types.
         case returnTypes([String])
+        /// This node is disambiguated by a mix of parameter types and return types.
+        case mixedTypes(parameterTypes: [String], returnTypes: [String])
 
         /// Makes a new disambiguation suffix string.
         func makeSuffix() -> String {
@@ -361,6 +383,9 @@ extension PathHierarchy.DisambiguationContainer {
             case .parameterTypes(let types):
                 // For example: "-(String,_)" or "-(_,Int)"` (a certain parameter has a certain type), or "-()" (has no parameters).
                 return "-(\(types.joined(separator: ",")))"
+
+            case .mixedTypes(parameterTypes: let parameterTypes, returnTypes: let returnTypes):
+                return "\(Self.parameterTypes(parameterTypes).makeSuffix())\(Self.returnTypes(returnTypes).makeSuffix())"
             }
         }
 
@@ -373,7 +398,7 @@ extension PathHierarchy.DisambiguationContainer {
                 return kind.map { .kind($0) } ?? self
             case .hash:
                 return hash.map { .hash($0) } ?? self
-            case .parameterTypes, .returnTypes:
+            case .parameterTypes, .returnTypes, .mixedTypes:
                 return self
             }
         }
@@ -382,36 +407,46 @@ extension PathHierarchy.DisambiguationContainer {
     private static func _disambiguateByTypeSignature(
         _ elements: [Element],
         types: (Element) -> [String]?,
-        makeDisambiguation: ([String]) -> Disambiguation,
-        remainingIDs: inout Set<ResolvedIdentifier?>
+        makeDisambiguation: (Element, [String]) -> Disambiguation,
+        remainingIDs: inout Set<ResolvedIdentifier>
     ) -> [(value: PathHierarchy.Node, disambiguation: Disambiguation)] {
         var collisions: [(value: PathHierarchy.Node, disambiguation: Disambiguation)] = []
+        // Assume that all elements will find a disambiguation (or close to it)
+        collisions.reserveCapacity(elements.count)
+
+        typealias ElementAndTypeNames = (element: Element, typeNames: [String])
+        var groupedByTypeCount: [Int: [ElementAndTypeNames]] = [:]
+        for element in elements {
+            guard let typeNames = types(element) else { continue }
+
+            groupedByTypeCount[typeNames.count, default: []].append((element, typeNames))
+        }
 
-        let groupedByTypeCount = [Int?: [Element]](grouping: elements, by: { types($0)?.count })
-        for (typesCount, elements) in groupedByTypeCount  {
-            guard let typesCount else { continue }
-            guard elements.count > 1 else {
+        for (numberOfTypeNames, elementAndTypeNamePairs) in groupedByTypeCount {
+            guard elementAndTypeNamePairs.count > 1 else {
                 // Only one element has this number of types. Disambiguate with only underscores.
-                let element = elements.first!
-                guard remainingIDs.contains(element.node.identifier) else { continue } // Don't disambiguate the same element more than once
-                collisions.append((value: element.node, disambiguation: makeDisambiguation(.init(repeating: "_", count: typesCount))))
-                remainingIDs.remove(element.node.identifier)
+                let (element, _) = elementAndTypeNamePairs.first!
+                guard remainingIDs.remove(element.node.identifier) != nil else {
+                    continue // Don't disambiguate the same element more than once
+                }
+                collisions.append((value: element.node, disambiguation: makeDisambiguation(element, .init(repeating: "_", count: numberOfTypeNames))))
                 continue
             }
-            guard typesCount > 0 else { continue } // Need at least one return value to disambiguate
 
-            for typeIndex in 0..<typesCount {
-                let grouped = [String: [Element]](grouping: elements, by: { types($0)![typeIndex] })
-                for (returnType, elements) in grouped where elements.count == 1 {
-                    // Only one element has this return type
-                    let element = elements.first!
-                    guard remainingIDs.contains(element.node.identifier) else { continue } // Don't disambiguate the same element more than once
-                    var disambiguation = [String](repeating: "_", count: typesCount)
-                    disambiguation[typeIndex] = returnType
-                    collisions.append((value: element.node, disambiguation: makeDisambiguation(disambiguation)))
-                    remainingIDs.remove(element.node.identifier)
-                    continue
+            guard numberOfTypeNames > 0 else {
+                continue // Need at least one type name to disambiguate (when there are multiple elements without parameters or return values)
+            }
+
+            let disambiguation = minimalSuggestedDisambiguation(forOverloadsAndTypeNames: elementAndTypeNamePairs)
+
+            for (pair, disambiguation) in zip(elementAndTypeNamePairs, disambiguation) {
+                guard let disambiguation else {
+                    continue // This element can't be uniquely disambiguated using these types
+                }
+                guard remainingIDs.remove(pair.element.node.identifier) != nil else {
+                    continue // Don't disambiguate the same element more than once
                 }
+                collisions.append((value: pair.element.node, disambiguation: makeDisambiguation(pair.element, disambiguation)))
             }
         }
         return collisions