Support suggesting a combination of parameter types and return types as disambiguation when the function returns 'void' (#1156)

* Support suggesting a combination of parameter types and return types as disambiguation when the function returns 'void'

rdar://143897549

* Update year in header comment for modified files

Author: d-ronnqvist

Sources/SwiftDocC/DocumentationService/Convert/Symbol Link Resolution/LinkCompletionTools.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2024 Apple Inc. and the Swift project authors
+ Copyright (c) 2024-2025 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information

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

@@ -266,8 +266,7 @@ extension PathHierarchy.DisambiguationContainer {
                 types: { element in
                     guard let parameterTypes = element.parameterTypes,
                           !parameterTypes.isEmpty,
-                          let returnTypes = element.returnTypes,
-                          !returnTypes.isEmpty
+                          let returnTypes = element.returnTypes
                     else {
                         return nil
                     }

Tests/SwiftDocCTests/Infrastructure/PathHierarchyTests.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2022-2024 Apple Inc. and the Swift project authors
+ Copyright (c) 2022-2025 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -3460,6 +3460,55 @@ class PathHierarchyTests: XCTestCase {
             ])
         }
 
+        // Each overload requires a combination parameters and return values to disambiguate
+        do {
+            //  Int   ->  ()
+            //  Bool  ->  ()
+            //  Int   ->  Int
+            let catalog = Folder(name: "unit-test.docc", content: [
+                JSONFile(name: "ModuleName.symbols.json", content: makeSymbolGraph(
+                    moduleName: "ModuleName",
+                    symbols: [
+                        //  Int   ->  Void
+                        makeSymbol(id: "function-overload-1", kind: .func, pathComponents: ["doSomething(first:)"], signature: .init(
+                            parameters: [
+                                makeParameter("first",  decl: [intType]), // Int
+                            ], returns: makeFragments([                   // ->
+                                voidType                                  // ()
+                            ])
+                        )),
+                        
+                        //  Bool   ->  Void
+                        makeSymbol(id: "function-overload-2", kind: .func, pathComponents: ["doSomething(first:)"], signature: .init(
+                            parameters: [
+                                makeParameter("first",  decl: [boolType]), // Bool
+                            ], returns: makeFragments([                    // ->
+                                voidType                                   // ()
+                            ])
+                        )),
+                        
+                        //  Int    ->  Int
+                        makeSymbol(id: "function-overload-3", kind: .func, pathComponents: ["doSomething(first:)"], signature: .init(
+                            parameters: [
+                                makeParameter("first",  decl: [intType]), // Int
+                            ], returns: makeFragments([                   // ->
+                                intType                                   // Int
+                            ])
+                        )),
+                    ]
+                ))
+            ])
+            
+            let (_, context) = try loadBundle(catalog: catalog)
+            let tree = context.linkResolver.localResolver.pathHierarchy
+            
+            try assertPathCollision("ModuleName/doSomething(first:)", in: tree, collisions: [
+                (symbolID: "function-overload-1", disambiguation: "-(Int)->()"), //  ( Int  )  ->  ()
+                (symbolID: "function-overload-2", disambiguation: "-(Bool)"),    //  ( Bool )
+                (symbolID: "function-overload-3", disambiguation: "->_"),        //            ->  _
+            ])
+        }
+        
         // Two overloads with more than 64 parameters, but some unique
         do {
             let spellOutFormatter = NumberFormatter()

Tests/SwiftDocCTests/Infrastructure/Symbol Link Resolution/LinkCompletionToolsTests.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2024 Apple Inc. and the Swift project authors
+ Copyright (c) 2024-2025 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -161,4 +161,25 @@ class LinkCompletionToolsTests: XCTestCase {
             "-(_,String)", "->Wrapped", "-(_,Double)",
         ])
     }
+    
+    func testSuggestingBothParameterAndReturnTypesInTheSameDisambiguation() {
+        let overloads = [
+            (parameters: ["Int"],  returns: []),      // (Int)  -> Void
+            (parameters: ["Bool"], returns: []),      // (Bool) -> Void
+            (parameters: ["Int"],  returns: ["Int"]), // (Int)  -> Int
+        ].map {
+            LinkCompletionTools.SymbolInformation(
+                kind: "func",
+                symbolIDHash: "\($0)".stableHashString,
+                parameterTypes: $0.parameters,
+                returnTypes: $0.returns
+            )
+        }
+        
+        XCTAssertEqual(LinkCompletionTools.suggestedDisambiguation(forCollidingSymbols: overloads), [
+            "-(Int)->()", // Only parameter type would be ambiguous with 3rd overload & only return type would be ambiguous with 2nd overload.
+            "-(Bool)",    // The only overload with a `Bool` value
+            "->_",        // The only overload that returns something
+        ])
+    }
 }