Populate abbreviated declaration fragments in external render nodes

Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver+DeprecatedCommunication.swift

@@ -162,6 +162,8 @@ extension OutOfProcessReferenceResolver {
         /// Information about the platforms and their versions where the resolved node is available, if any.
         public let platforms: [PlatformAvailability]?
         /// Information about the resolved declaration fragments, if any.
+        ///
+        /// This is expected to be an abbreviated declaration for the symbol.
         public let declarationFragments: DeclarationFragments?
 
         // We use the real types here because they're Codable and don't have public member-wise initializers.
@@ -205,7 +207,7 @@ extension OutOfProcessReferenceResolver {
         ///   - language: The resolved language.
         ///   - availableLanguages: The languages where the resolved node is available.
         ///   - platforms: The platforms and their versions where the resolved node is available, if any.
-        ///   - declarationFragments: The resolved declaration fragments, if any.
+        ///   - declarationFragments: The resolved declaration fragments, if any. This is expected to be an abbreviated declaration for the symbol.
         ///   - topicImages: Images that are used to represent the summarized element.
         ///   - references: References used in the content of the summarized element.
         ///   - variants: The variants of content for this resolver information.
@@ -259,6 +261,8 @@ extension OutOfProcessReferenceResolver {
             public let language: VariantValue<SourceLanguage>
             /// The declaration fragments of the variant or `nil` if the declaration is the same as the resolved information.
             ///
+            /// This is expected to be an abbreviated declaration for the symbol.
+            ///
             /// If the resolver information has a declaration but the variant doesn't, this property will be `Optional.some(nil)`.
             public let declarationFragments: VariantValue<DeclarationFragments?>
 
@@ -271,7 +275,7 @@ extension OutOfProcessReferenceResolver {
             ///   - title: The resolved title
             ///   - abstract: The resolved (plain text) abstract.
             ///   - language: The resolved language.
-            ///   - declarationFragments: The resolved declaration fragments, if any.
+            ///   - declarationFragments: The resolved declaration fragments, if any. This is expected to be an abbreviated declaration for the symbol.
             public init(
                 traits: [RenderNode.Variant.Trait],
                 kind: VariantValue<DocumentationNode.Kind> = nil,

Sources/SwiftDocC/Infrastructure/Link Resolution/ExternalPathHierarchyResolver.swift

@@ -58,13 +58,13 @@ final class ExternalPathHierarchyResolver {
             return collidingNode.name
         }
         if let symbolID = collidingNode.symbol?.identifier {
-            if symbolID.interfaceLanguage == summary.language.id, let fragments = summary.declarationFragments {
-                return fragments.plainTextDeclaration()
+            if symbolID.interfaceLanguage == summary.language.id, let plainTextDeclaration = summary.plainTextDeclaration {
+                return plainTextDeclaration
             }
             if let variant = summary.variants.first(where: { $0.traits.contains(.interfaceLanguage(symbolID.interfaceLanguage)) }),
-               let fragments = variant.declarationFragments ?? summary.declarationFragments
+               let plainTextDeclaration = variant.plainTextDeclaration ?? summary.plainTextDeclaration
             {
-                return fragments.plainTextDeclaration()
+                return plainTextDeclaration
             }
         }
         return summary.title
@@ -153,12 +153,6 @@ final class ExternalPathHierarchyResolver {
     }
 }
 
-private extension Sequence<DeclarationRenderSection.Token> {
-    func plainTextDeclaration() -> String {
-        return self.map(\.text).joined().split(whereSeparator: { $0.isWhitespace || $0.isNewline }).joined(separator: " ")
-    }
-}
-
 // MARK: ExternalEntity
 
 extension LinkDestinationSummary {
@@ -177,7 +171,8 @@ extension LinkDestinationSummary {
 
         var titleVariants = VariantCollection(defaultValue: title)
         var abstractVariants = VariantCollection(defaultValue: abstract ?? [])
-        var fragmentVariants = VariantCollection(defaultValue: declarationFragments)
+        var fragmentVariants = VariantCollection(defaultValue: subheadingDeclarationFragments)
+        var navigatorTitleVariants = VariantCollection(defaultValue: navigatorDeclarationFragments)
 
         for variant in variants {
             let traits = variant.traits
@@ -187,9 +182,12 @@ extension LinkDestinationSummary {
             if let abstract = variant.abstract {
                 abstractVariants.variants.append(.init(traits: traits, patch: [.replace(value: abstract ?? [])]))
             }
-            if let fragment = variant.declarationFragments {
+            if let fragment = variant.subheadingDeclarationFragments {
                 fragmentVariants.variants.append(.init(traits: traits, patch: [.replace(value: fragment)]))
             }
+            if let navigatorTitle = variant.navigatorDeclarationFragments {
+                navigatorTitleVariants.variants.append(.init(traits: traits, patch: [.replace(value: navigatorTitle)]))
+            }
         }
 
         return TopicRenderReference(
@@ -201,7 +199,7 @@ extension LinkDestinationSummary {
             required: false,
             role: role,
             fragmentsVariants: fragmentVariants,
-            navigatorTitleVariants: .init(defaultValue: nil),
+            navigatorTitleVariants: navigatorTitleVariants,
             estimatedTime: nil,
             conformance: nil,
             isBeta: isBeta,

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
 }