Populate declaration fragments in navigator metadata for external links

Now that the declaration fragments will be the abbreviated declaration fragments from `LinkDestinationSummary`, we can propagate those to the navigator metadata for them to be used to inform the title of the navigator item [1].

Fixes rdar://156488052.

[1]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/Navigator/RenderNode%2BNavigatorIndex.swift#L140

Author: anferbui

Sources/SwiftDocC/Infrastructure/Link Resolution/LinkResolver+NavigatorIndex.swift

@@ -69,6 +69,13 @@ package struct ExternalRenderNode {
         topicRenderReference.navigatorTitleVariants
     }
 
+    /// The variants of the abbreviated declaration of the symbol to display in links and fall-back to in navigation.
+    ///
+    /// This value is `nil` if the referenced page is not a symbol.
+    var fragmentsVariants: VariantCollection<[DeclarationRenderSection.Token]?> {
+        topicRenderReference.fragmentsVariants
+    }
+    
     /// Author provided images that represent this page.
     var images: [TopicImage] {
         entity.topicImages ?? []
@@ -129,7 +136,8 @@ struct NavigatorExternalRenderNode: NavigatorIndexableRenderNodeRepresentation {
             role: renderNode.role,
             symbolKind: renderNode.symbolKind?.renderingIdentifier,
             images: renderNode.images,
-            isBeta: renderNode.isBeta
+            isBeta: renderNode.isBeta,
+            fragments: renderNode.fragmentsVariants.value(for: traits)
         )
     }
 }
@@ -143,19 +151,16 @@ struct ExternalRenderNodeMetadataRepresentation: NavigatorIndexableRenderMetadat
     var symbolKind: String?
     var images: [TopicImage]
     var isBeta: Bool
+    var fragments: [DeclarationRenderSection.Token]?
 
     // Values that we have insufficient information to derive.
     // These are needed to conform to the navigator indexable metadata protocol.
     //
-    // The fragments that we get as part of the external link are the full declaration fragments.
-    // These are too verbose for the navigator, so instead of using them, we rely on the title, navigator title and symbol kind instead.
-    //
     // The role heading is used to identify Property Lists.
     // The value being missing is used for computing the final navigator title.
     //
     // The platforms are used for generating the availability index,
     // but doesn't affect how the node is rendered in the sidebar.
-    var fragments: [DeclarationRenderSection.Token]? = nil
     var roleHeading: String? = nil
     var platforms: [AvailabilityRenderItem]? = nil
 }

Tests/SwiftDocCTests/Indexing/ExternalRenderNodeTests.swift

@@ -41,6 +41,11 @@ class ExternalRenderNodeTests: XCTestCase {
                 title: "SwiftSymbol",
                 kind: .class,
                 language: .swift,
+                declarationFragments: .init(declarationFragments: [
+                    .init(kind: .keyword, spelling: "class", preciseIdentifier: nil),
+                    .init(kind: .text, spelling: " ", preciseIdentifier: nil),
+                    .init(kind: .identifier, spelling: "SwiftSymbol", preciseIdentifier: nil)
+                ]),
                 platforms: [.init(name: "iOS", introduced: nil, isBeta: true)]
             )
         )
@@ -50,6 +55,13 @@ class ExternalRenderNodeTests: XCTestCase {
                 title: "ObjCSymbol",
                 kind: .function,
                 language: .objectiveC,
+                declarationFragments: .init(declarationFragments: [
+                    .init(kind: .text, spelling: "- ", preciseIdentifier: nil),
+                    .init(kind: .text, spelling: "(", preciseIdentifier: nil),
+                    .init(kind: .typeIdentifier, spelling: "void", preciseIdentifier: nil),
+                    .init(kind: .text, spelling: ") ", preciseIdentifier: nil),
+                    .init(kind: .identifier, spelling: "ObjCSymbol", preciseIdentifier: nil)
+                ]),
                 platforms: [.init(name: "macOS", introduced: nil, isBeta: false)]
             )
         )
@@ -152,12 +164,14 @@ class ExternalRenderNodeTests: XCTestCase {
         )
         XCTAssertEqual(swiftNavigatorExternalRenderNode.metadata.title, swiftTitle)
         XCTAssertFalse(swiftNavigatorExternalRenderNode.metadata.isBeta)
-
+        XCTAssertEqual(swiftNavigatorExternalRenderNode.metadata.fragments, swiftFragments)
+        
         let objcNavigatorExternalRenderNode = try XCTUnwrap(
             NavigatorExternalRenderNode(renderNode: externalRenderNode, trait: .interfaceLanguage(SourceLanguage.objectiveC.id))
         )
         XCTAssertEqual(objcNavigatorExternalRenderNode.metadata.title, objcTitle)
         XCTAssertFalse(objcNavigatorExternalRenderNode.metadata.isBeta)
+        XCTAssertEqual(objcNavigatorExternalRenderNode.metadata.fragments, objcFragments)
     }
 
     func testNavigatorWithExternalNodes() async throws {
@@ -218,19 +232,38 @@ class ExternalRenderNodeTests: XCTestCase {
         XCTAssertEqual(renderIndex.interfaceLanguages[SourceLanguage.swift.id]?.count(where: \.isExternal), 0)
         XCTAssertEqual(renderIndex.interfaceLanguages[SourceLanguage.objectiveC.id]?.count(where: \.isExternal), 0)
 
+        
+        func externalNodes(by language: SourceLanguage) -> [RenderIndex.Node]? {
+            renderIndex.interfaceLanguages[language.id]?.first?.children?.filter(\.isExternal)
+        }
+        
         // Verify that the curated external links are part of the index.
-        let swiftExternalNodes = (renderIndex.interfaceLanguages[SourceLanguage.swift.id]?.first?.children?.filter(\.isExternal) ?? []).sorted(by: \.title)
-        let objcExternalNodes  = (renderIndex.interfaceLanguages[SourceLanguage.objectiveC.id]?.first?.children?.filter(\.isExternal) ?? []).sorted(by: \.title)
+        let swiftExternalNodes = try XCTUnwrap(externalNodes(by: .swift))
         XCTAssertEqual(swiftExternalNodes.count, 2)
+
+        let objcExternalNodes = try XCTUnwrap(externalNodes(by: .objectiveC))
         XCTAssertEqual(objcExternalNodes.count, 2)
-        XCTAssertEqual(swiftExternalNodes.map(\.title), ["SwiftArticle", "SwiftSymbol"])
-        XCTAssertEqual(objcExternalNodes.map(\.title),  ["ObjCArticle",  "ObjCSymbol"])
-        XCTAssert(swiftExternalNodes.first?.isBeta == false)
-        XCTAssert(swiftExternalNodes.last?.isBeta == true)
-        XCTAssert(objcExternalNodes.first?.isBeta == true)
-        XCTAssert(objcExternalNodes.last?.isBeta == false)
-        XCTAssertEqual(swiftExternalNodes.map(\.type), ["article", "class"])
-        XCTAssertEqual(objcExternalNodes.map(\.type), ["article", "func"])
+
+        let swiftArticleExternalNode = try XCTUnwrap(swiftExternalNodes.first(where: { $0.path == "/path/to/external/swiftarticle" }))
+        let swiftSymbolExternalNode = try XCTUnwrap(swiftExternalNodes.first(where: { $0.path == "/path/to/external/swiftsymbol" }))
+        let objcArticleExternalNode = try XCTUnwrap(objcExternalNodes.first(where: { $0.path == "/path/to/external/objcarticle" }))
+        let objcSymbolExternalNode = try XCTUnwrap(objcExternalNodes.first(where: { $0.path == "/path/to/external/objcsymbol" }))
+
+        XCTAssertEqual(swiftArticleExternalNode.title, "SwiftArticle")
+        XCTAssertEqual(swiftArticleExternalNode.isBeta, false)
+        XCTAssertEqual(swiftArticleExternalNode.type, "article")
+
+        XCTAssertEqual(swiftSymbolExternalNode.title, "SwiftSymbol")  // Classes don't use declaration fragments in their navigator title
+        XCTAssertEqual(swiftSymbolExternalNode.isBeta, true)
+        XCTAssertEqual(swiftSymbolExternalNode.type, "class")
+
+        XCTAssertEqual(objcArticleExternalNode.title, "ObjCArticle")
+        XCTAssertEqual(objcArticleExternalNode.isBeta, true)
+        XCTAssertEqual(objcArticleExternalNode.type, "article")
+
+        XCTAssertEqual(objcSymbolExternalNode.title, "- (void) ObjCSymbol")
+        XCTAssertEqual(objcSymbolExternalNode.isBeta, false)
+        XCTAssertEqual(objcSymbolExternalNode.type, "func")
     }
 
     func testNavigatorWithExternalNodesOnlyAddsCuratedNodesToNavigator() async throws {
@@ -299,7 +332,7 @@ class ExternalRenderNodeTests: XCTestCase {
         XCTAssertEqual(swiftExternalNodes.count, 1)
         XCTAssertEqual(objcExternalNodes.count, 1)
         XCTAssertEqual(swiftExternalNodes.map(\.title), ["SwiftArticle"])
-        XCTAssertEqual(objcExternalNodes.map(\.title), ["ObjCSymbol"])
+        XCTAssertEqual(objcExternalNodes.map(\.title), ["- (void) ObjCSymbol"])
         XCTAssertEqual(swiftExternalNodes.map(\.type), ["article"])
         XCTAssertEqual(objcExternalNodes.map(\.type), ["func"])
     }

Tests/SwiftDocCTests/Infrastructure/TestExternalReferenceResolvers.swift

@@ -92,6 +92,7 @@ class TestMultiResultExternalReferenceResolver: ExternalDocumentationSource {
             title: entityInfo.title,
             availableLanguages: [entityInfo.language],
             platforms: entityInfo.platforms,
+            declarationFragments: entityInfo.declarationFragments?.declarationFragments.map { .init(fragment: $0, identifier: nil) },
             topicImages: entityInfo.topicImages?.map(\.0),
             references: entityInfo.topicImages?.map { topicImage, altText in
                 ImageReference(identifier: topicImage.identifier, altText: altText, imageAsset: assetsToReturn[topicImage.identifier.identifier] ?? .init())