use SymbolKit's "alternate declarations" in declarations sections (#654)

rdar://70594078

Author: QuietMisdreavus

Package.resolved

@@ -9,6 +9,7 @@
 */
 
 import Foundation
+import SymbolKit
 
 /// Translates a symbol's declaration into a render node's Declarations section.
 struct DeclarationsSectionTranslator: RenderSectionTranslator {
@@ -23,27 +24,28 @@ struct DeclarationsSectionTranslator: RenderSectionTranslator {
             guard !declaration.isEmpty else {
                 return nil
             }
-            
+
+            func translateFragment(_ token: SymbolGraph.Symbol.DeclarationFragments.Fragment) -> DeclarationRenderSection.Token {
+                // Create a reference if one found
+                var reference: ResolvedTopicReference?
+                if let preciseIdentifier = token.preciseIdentifier,
+                   let resolved = renderNodeTranslator.context.symbolIndex[preciseIdentifier] {
+                    reference = resolved
+
+                    // Add relationship to render references
+                    renderNodeTranslator.collectedTopicReferences.append(resolved)
+                }
+
+                // Add the declaration token
+                return DeclarationRenderSection.Token(fragment: token, identifier: reference?.absoluteString)
+            }
+
             var declarations = [DeclarationRenderSection]()
             for pair in declaration {
                 let (platforms, declaration) = pair
 
-                let renderedTokens = declaration.declarationFragments.map { token -> DeclarationRenderSection.Token in
-                    
-                    // Create a reference if one found
-                    var reference: ResolvedTopicReference?
-                    if let preciseIdentifier = token.preciseIdentifier,
-                       let resolved = renderNodeTranslator.context.symbolIndex[preciseIdentifier] {
-                        reference = resolved
-                        
-                        // Add relationship to render references
-                        renderNodeTranslator.collectedTopicReferences.append(resolved)
-                    }
-                    
-                    // Add the declaration token
-                    return DeclarationRenderSection.Token(fragment: token, identifier: reference?.absoluteString)
-                }
-                
+                let renderedTokens = declaration.declarationFragments.map(translateFragment)
+
                 let platformNames = platforms.sorted { (lhs, rhs) -> Bool in
                     guard let lhsValue = lhs, let rhsValue = rhs else {
                         return lhs == nil
@@ -59,7 +61,28 @@ struct DeclarationsSectionTranslator: RenderSectionTranslator {
                     )
                 )
             }
-        
+
+            if let alternateDeclarations = symbol.alternateDeclarationVariants[trait] {
+                for pair in alternateDeclarations {
+                    let (platforms, decls) = pair
+                    for alternateDeclaration in decls {
+                        let renderedTokens = alternateDeclaration.declarationFragments.map(translateFragment)
+
+                        let platformNames = platforms
+                            .compactMap { $0 }
+                            .sorted(by: \.rawValue)
+
+                        declarations.append(
+                            DeclarationRenderSection(
+                                languages: [trait.interfaceLanguage ?? renderNodeTranslator.identifier.sourceLanguage.id],
+                                platforms: platformNames,
+                                tokens: renderedTokens
+                            )
+                        )
+                    }
+                }
+            }
+
             return DeclarationsRenderSection(declarations: declarations)
         }
     }

Sources/SwiftDocC/Model/Rendering/RenderSectionTranslator/DeclarationsSectionTranslator.swift

@@ -150,7 +150,10 @@ public final class Symbol: Semantic, Abstracted, Redirected, AutomaticTaskGroups
     public var declarationVariants = DocumentationDataVariants<[[PlatformName?]: SymbolGraph.Symbol.DeclarationFragments]>(
         defaultVariantValue: [:]
     )
-    
+
+    /// The symbols alternate declarations in each language variant the symbol is available in.
+    public var alternateDeclarationVariants = DocumentationDataVariants<[[PlatformName?]: [SymbolGraph.Symbol.DeclarationFragments]]>()
+
     public var locationVariants = DocumentationDataVariants<SymbolGraph.Symbol.Location>()
 
     /// The symbol's availability or conformance constraints, in each language variant the symbol is available in.
@@ -307,6 +310,8 @@ public final class Symbol: Semantic, Abstracted, Redirected, AutomaticTaskGroups
                     self.locationVariants[trait] = location
                 case let spi as SymbolGraph.Symbol.SPI:
                     self.isSPIVariants[trait] = spi.isSPI
+                case let alternateDeclarations as SymbolGraph.Symbol.AlternateDeclarations:
+                    self.alternateDeclarationVariants[trait] = [[platformNameVariants[trait]]: alternateDeclarations.declarations]
                 default: break;
                 }
             }

Sources/SwiftDocC/Semantics/Symbol/Symbol.swift

@@ -80,4 +80,25 @@ class DeclarationsRenderSectionTests: XCTestCase {
         let value = try JSONDecoder().decode(DeclarationsRenderSection.self, from: jsonData)
         try assertRoundTripCoding(value)
     }
+
+    func testAlternateDeclarations() throws {
+        let (bundle, context) = try testBundleAndContext(named: "AlternateDeclarations")
+        let reference = ResolvedTopicReference(
+            bundleIdentifier: bundle.identifier,
+            path: "/documentation/AlternateDeclarations/MyClass/present(completion:)",
+            sourceLanguage: .swift
+        )
+        let symbol = try XCTUnwrap(context.entity(with: reference).semantic as? Symbol)
+        var translator = RenderNodeTranslator(
+            context: context,
+            bundle: bundle,
+            identifier: reference,
+            source: nil
+        )
+        let renderNode = try XCTUnwrap(translator.visitSymbol(symbol) as? RenderNode)
+        let declarationsSection = try XCTUnwrap(renderNode.primaryContentSections.compactMap({ $0 as? DeclarationsRenderSection }).first)
+
+        XCTAssertEqual(declarationsSection.declarations.count, 2)
+        XCTAssert(declarationsSection.declarations.allSatisfy({ $0.platforms == [.macOS] }))
+    }
 }

Tests/SwiftDocCTests/Rendering/DeclarationsRenderSectionTests.swift

@@ -0,0 +1,9 @@
+# ``AlternateDeclarations``
+
+This bundle contains a class translated from Objective-C. That class contains one method, which was
+written to accept a completion handler. The Swift translation converted this into two methods: one
+with the original completion handler parameter, and one that uses `async`/`await`. This bundle
+exists to test SymbolKit's "alternate declarations" mechanism and ensure that Swift-DocC converts it
+into a Declarations section with both declarations.
+
+<!-- Copyright (c) 2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->