Support documenting parameters and return values that only appear in some alternate signatures

rdar://137964801

Author: d-ronnqvist

Sources/SwiftDocC/Model/ParametersAndReturnValidator.swift

@@ -293,38 +293,26 @@ struct ParametersAndReturnValidator {
     private static func traitSpecificSignatures(_ symbol: UnifiedSymbolGraph.Symbol) -> Signatures? {
         var signatures: [DocumentationDataVariantsTrait: SymbolGraph.Symbol.FunctionSignature] = [:]
         for (selector, mixin) in symbol.mixins {
-            guard let signature = mixin.getValueIfPresent(for: SymbolGraph.Symbol.FunctionSignature.self) else {
+            guard var signature = mixin.getValueIfPresent(for: SymbolGraph.Symbol.FunctionSignature.self) else {
                 continue
             }
 
+            if let alternateSymbols = mixin.getValueIfPresent(for: SymbolGraph.Symbol.AlternateSymbols.self) {
+                for alternateSymbol in alternateSymbols.alternateSymbols {
+                    guard let alternateSignature = alternateSymbol.functionSignature else { continue }
+                    signature.merge(with: alternateSignature, selector: selector)
+                }
+            }
+            
             let trait = DocumentationDataVariantsTrait(for: selector)
             // Check if we've already encountered a different signature for another platform
-            guard var existing = signatures.removeValue(forKey: trait) else {
+            guard let existing = signatures.removeValue(forKey: trait) else {
                 signatures[trait] = signature
                 continue
             }
 
-            // An internal helper function that compares parameter names
-            func hasSameNames(_ lhs: SymbolGraph.Symbol.FunctionSignature.FunctionParameter, _ rhs: SymbolGraph.Symbol.FunctionSignature.FunctionParameter) -> Bool {
-                lhs.name == rhs.name && lhs.externalName == rhs.externalName
-            }
-            // If the two signatures have different parameters, add any missing parameters.
-            // This allows for documenting parameters that are only available on some platforms.
-            //
-            // Note: Doing this redundant `elementsEqual(_:by:)` check is significantly faster in the common case when all platforms have the same signature.
-            // In the rare case where platforms have different signatures, the overhead of checking `elementsEqual(_:by:)` first is too small to measure.
-            if !existing.parameters.elementsEqual(signature.parameters, by: hasSameNames) {
-                for case .insert(offset: let offset, element: let element, _) in signature.parameters.difference(from: existing.parameters, by: hasSameNames) {
-                    existing.parameters.insert(element, at: offset)
-                }
-            }
-            
-            // If the already encountered signature has a void return type, replace it with the non-void return type.
-            // This allows for documenting the return values that are only available on some platforms.
-            if existing.returns != signature.returns, existing.returns == knownVoidReturnValuesByLanguage[.init(id: selector.interfaceLanguage)] {
-                existing.returns = signature.returns
-            }
-            signatures[trait] = existing
+            signature.merge(with: existing, selector: selector)
+            signatures[trait] = signature
         }
 
         guard !signatures.isEmpty else { return nil }
@@ -673,3 +661,36 @@ struct ParametersAndReturnValidator {
         "- \(standalone ? "Parameter " : "")\(name): <#parameter description#>"
     }
 }
+
+// MARK: Helper extensions
+
+private extension SymbolGraph.Symbol.FunctionSignature {
+    mutating func merge(with signature: Self, selector: UnifiedSymbolGraph.Selector) {
+        // An internal helper function that compares parameter names
+        func hasSameNames(_ lhs: Self.FunctionParameter, _ rhs: Self.FunctionParameter) -> Bool {
+            lhs.name == rhs.name && lhs.externalName == rhs.externalName
+        }
+        // If the two signatures have different parameters, add any missing parameters.
+        // This allows for documenting parameters that are only available on some platforms.
+        //
+        // Note: Doing this redundant `elementsEqual(_:by:)` check is significantly faster in the common case when all platforms have the same signature.
+        // In the rare case where platforms have different signatures, the overhead of checking `elementsEqual(_:by:)` first is too small to measure.
+        if !self.parameters.elementsEqual(signature.parameters, by: hasSameNames) {
+            for case .insert(offset: let offset, element: let element, _) in signature.parameters.difference(from: self.parameters, by: hasSameNames) {
+                self.parameters.insert(element, at: offset)
+            }
+        }
+        
+        // If the already encountered signature has a void return type, replace it with the non-void return type.
+        // This allows for documenting the return values that are only available on some platforms.
+        if self.returns != signature.returns,
+           let knownVoidReturnValues = ParametersAndReturnValidator.knownVoidReturnValuesByLanguage[.init(id: selector.interfaceLanguage)]
+        {
+            for knownVoidReturnValue in knownVoidReturnValues where [knownVoidReturnValue] == self.returns {
+                // The current return value was a known void return value so we replace it with the new return value.
+                self.returns = signature.returns
+                return
+            }
+        }
+    }
+}

Tests/SwiftDocCTests/Model/ParametersAndReturnValidatorTests.swift

@@ -111,6 +111,36 @@ class ParametersAndReturnValidatorTests: XCTestCase {
         }
     }
 
+    func testParametersWithAlternateSignatures() throws {
+        let (_, _, context) = try testBundleAndContext(copying: "AlternateDeclarations") { url in
+            try """
+            # ``MyClass/present(completion:)``
+            
+            @Metadata {
+              @DocumentationExtension(mergeBehavior: override)
+            }
+            
+            Override the documentation with a parameter section that raise warnings.
+            
+            - Parameters:
+              - completion: Description of the parameter that's available in some alternatives.
+            - Returns: Description of the return value that's available for some other alternatives.
+            """.write(to: url.appendingPathComponent("extension.md"), atomically: true, encoding: .utf8)
+        }
+        
+        let reference = try XCTUnwrap(context.soleRootModuleReference).appendingPath("MyClass/present(completion:)")
+        let node = try context.entity(with: reference)
+        let symbolSemantic = try XCTUnwrap(node.semantic as? Symbol)
+        
+        let swiftParameterNames = symbolSemantic.parametersSectionVariants.firstValue?.parameters
+        
+        XCTAssertEqual(swiftParameterNames?.map(\.name), ["completion"])
+        XCTAssertEqual(swiftParameterNames?.map { _format($0.contents) }, ["Description of the parameter that’s available in some alternatives."])
+        
+        let swiftReturnsContent = symbolSemantic.returnsSection.map { _format($0.content) }
+        XCTAssertEqual(swiftReturnsContent, "Description of the return value that’s available for some other alternatives.")
+    }
+    
     func testParameterDiagnosticsInDocumentationExtension() throws {
         let (url, _, context) = try testBundleAndContext(copying: "ErrorParameters") { url in
             try """
@@ -200,11 +230,6 @@ class ParametersAndReturnValidatorTests: XCTestCase {
         let (_, _, context) = try testBundleAndContext(named: "GeometricalShapes")
         XCTAssertEqual(context.problems.map(\.diagnostic.summary), [])
 
-        // A small test helper to format markup for test assertions in this test.
-        func _format(_ markup: [any Markup]) -> String {
-            markup.map { $0.format() }.joined()
-        }
-        
         let reference = try XCTUnwrap(context.knownPages.first(where: { $0.lastPathComponent == "isEmpty" }))
         let node = try context.entity(with: reference)
 
@@ -734,3 +759,8 @@ class ParametersAndReturnValidatorTests: XCTestCase {
         )
     }
 }
+
+// A small test helper to format markup for test assertions in this file.
+private func _format(_ markup: [any Markup]) -> String {
+    markup.map { $0.format() }.joined()
+}