Add a suffix property to LinkCompletionTools.ParsedDisambiguation (#1151)

* Add a `suffix` property to `LinkCompletionTools.ParsedDisambiguation`

* Fix parsing bug for disambiguation with both parameter and return types

Author: d-ronnqvist

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

@@ -74,6 +74,39 @@ public enum LinkCompletionTools {
                 self = .none
             }
         }
+        
+        /// A string representation of the disambiguation.
+        public var suffix: String {
+            typealias Disambiguation = PathHierarchy.DisambiguationContainer.Disambiguation
+            
+            switch self {
+            case .kindAndOrHash(let kind?, nil):
+                return Disambiguation.kind(kind).makeSuffix()
+            case .kindAndOrHash(nil,       let hash?):
+                return Disambiguation.hash(hash).makeSuffix()
+            case .kindAndOrHash(let kind?, let hash?): // This is never necessary but a developer could redundantly write it in a parsed link
+                return Disambiguation.kind(kind).makeSuffix() + Disambiguation.hash(hash).makeSuffix()
+                
+            case .typeSignature(let parameterTypes?, nil):
+                return Disambiguation.parameterTypes(parameterTypes).makeSuffix()
+            case .typeSignature(nil,                 let returnTypes?):
+                return Disambiguation.returnTypes(returnTypes).makeSuffix()
+            case .typeSignature(let parameterTypes?, let returnTypes?):
+                return Disambiguation.mixedTypes(parameterTypes: parameterTypes, returnTypes: returnTypes).makeSuffix()
+                
+            // Unexpected error cases
+            case .kindAndOrHash(kind: nil, hash: nil):
+                assertionFailure("Parsed `.kindAndOrHash` disambiguation missing both kind and hash should use `.none` instead. This is a logic bug.")
+                return Disambiguation.none.makeSuffix()
+            case .typeSignature(parameterTypes: nil, returnTypes: nil):
+                assertionFailure("Parsed `.typeSignature` disambiguation missing both parameter types and return types should use `.none` instead. This is a logic bug.")
+                return Disambiguation.none.makeSuffix()
+                
+            // Since this is within DocC we want to have an error if we don't handle new future cases.
+            case .none, ._nonFrozenEnum_useDefaultCase:
+                return Disambiguation.none.makeSuffix()
+            }
+        }
     }
 
     /// Suggests the minimal most readable disambiguation string for each symbol with the same name.

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

@@ -162,6 +162,61 @@ class LinkCompletionToolsTests: XCTestCase {
         ])
     }
 
+    func testDisambiguationSuffixStrings() {
+        typealias Disambiguation = LinkCompletionTools.ParsedDisambiguation
+        
+        XCTAssertEqual(Disambiguation.none.suffix,"")
+        
+        XCTAssertEqual(Disambiguation.kindAndOrHash(kind: "class", hash: nil).suffix,
+                       "-class")
+        XCTAssertEqual(Disambiguation.kindAndOrHash(kind: nil, hash: "z3jl").suffix,
+                       "-z3jl")
+        
+        XCTAssertEqual(Disambiguation.typeSignature(parameterTypes: [], returnTypes: nil).suffix,
+                       "-()")
+        XCTAssertEqual(Disambiguation.typeSignature(parameterTypes: ["Int"], returnTypes: nil).suffix,
+                       "-(Int)")
+        XCTAssertEqual(Disambiguation.typeSignature(parameterTypes: ["Int", "_", "String"], returnTypes: nil).suffix,
+                       "-(Int,_,String)")
+        
+        XCTAssertEqual(Disambiguation.typeSignature(parameterTypes: nil, returnTypes: []).suffix,
+                       "->()")
+        XCTAssertEqual(Disambiguation.typeSignature(parameterTypes: nil, returnTypes: ["Int"]).suffix,
+                       "->Int")
+        XCTAssertEqual(Disambiguation.typeSignature(parameterTypes: nil, returnTypes: ["Int", "_", "String"]).suffix,
+                       "->(Int,_,String)")
+        
+        XCTAssertEqual(Disambiguation.typeSignature(parameterTypes: ["_", "Bool"], returnTypes: []).suffix,
+                       "-(_,Bool)->()")
+        XCTAssertEqual(Disambiguation.typeSignature(parameterTypes: ["_", "Bool"], returnTypes: ["Int"]).suffix,
+                       "-(_,Bool)->Int")
+        XCTAssertEqual(Disambiguation.typeSignature(parameterTypes: ["_", "Bool"], returnTypes: ["Int", "_", "String"]).suffix,
+                       "-(_,Bool)->(Int,_,String)")
+    }
+    
+    func testParsingDisambiguationSuffixStrings() throws {
+        for disambiguationSuffixString in [
+            "",
+            "-class",
+            "-z3jl",
+            
+            "-()",
+            "-(Int)",
+            "-(Int,_,String)",
+            
+            "->()",
+            "->Int",
+            "->(Int,_,String)",
+            
+            "-(_,Bool)->()",
+            "-(_,Bool)->Int",
+            "-(_,Bool)->(Int,_,String)",
+        ] {
+            let parsedLinkComponent = try XCTUnwrap(LinkCompletionTools.parse(linkString: "SymbolName\(disambiguationSuffixString)").first)
+            XCTAssertEqual(parsedLinkComponent.disambiguation.suffix, disambiguationSuffixString)
+        }
+    }
+
     func testSuggestingBothParameterAndReturnTypesInTheSameDisambiguation() {
         let overloads = [
             (parameters: ["Int"],  returns: []),      // (Int)  -> Void