Add the abbreviated declaration fragments to LinkDestinationSummary

LinkDestinationSummary contains a summary of an element that you can link to from outside the documentation bundle. [1]
This information is meant to be used by a server to provide information to an out-of-process resolver to resolve links to external entities, so that the partner implementation of `LinkDestinationSummary` is `OutOfProcessReferenceResolver.ResolvedInformation` [2].
As part of `LinkDestinationSummary`, we store the full declaration fragments of the symbol [3][4].

However, currently `OutOfProcessReferenceResolver` is using these full declaration fragments to populate `TopicRenderReference.fragmentsVariants` [5], which expects the abbreviated declaration fragments [6].
These abbreviated declaration fragments are meant to be used in the Topics section and the navigation index in order to reduce verbosity and improve readability by removing any declaration fragments non-essential to the core of the symbol declaration.

These abbreviated declaration fragments are not captured as part of `LinkDestinationSummary` or `OutOfProcessReferenceResolver.ResolvedInformation`. To start capturing this information, this commit modifies `LinkDestinationSummary` to add a new optional field `subHeadingDeclarationFragments` which stores the abbreviated declaration fragments  from `renderNode.metadata.fragmentsVariants` (abbreviated declaration fragments are derived from the `subHeading` of the symbol [7], further processed during the render node transformation phase, and finally stored as `renderNode.metadata.fragmentsVariants` [8]).

This will enable us to use them in `OutOfProcessReferenceResolver.ResolvedInformation` to initialise `TopicRenderReference.fragmentsVariants` with the expected value.

The final goal is for a symbol's representation in the Topics section and the navigation index to look the same regardless of whether the symbol is a local or external one.

Fixes rdar://156488052.

Alternatives considered:
------------------------

Considered modifying `LinkDestinationSummary.declarationFragments` instead of adding a new optional field, however the full declaration fragments are used to determine the full name [9] of the symbol for diagnostic reporting [10].

By introducing a new field we also ensure this is a non-breaking change.

[1]:  https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift#L66
[2]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Infrastructure/External%20Data/OutOfProcessReferenceResolver.swift#L558-L562
[3]: https://github.com/swiftlang/swift-docc/blob/1b4a1850dd2785a8ebabded139ae0af3551bb029/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift#L140-L141
[4]: https://github.com/swiftlang/swift-docc/blob/1b4a1850dd2785a8ebabded139ae0af3551bb029/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift#L445
[5]: https://github.com/swiftlang/swift-docc/blob/1b4a1850dd2785a8ebabded139ae0af3551bb029/Sources/SwiftDocC/Infrastructure/External%20Data/OutOfProcessReferenceResolver.swift#L169
[6]: https://github.com/swiftlang/swift-docc/blob/1b4a1850dd2785a8ebabded139ae0af3551bb029/Sources/SwiftDocC/Model/Rendering/References/TopicRenderReference.swift#L50-L53
[7]: https://github.com/swiftlang/swift-docc-symbolkit/blob/ebe89c7da4cf03ded04cd708f3399087c6f2dad7/Sources/SymbolKit/SymbolGraph/Symbol/Names.swift#L28-L31
[8]: https://github.com/swiftlang/swift-docc/blob/1b4a1850dd2785a8ebabded139ae0af3551bb029/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift#L1304
[9]: https://github.com/swiftlang/swift-docc/blob/1b4a1850dd2785a8ebabded139ae0af3551bb029/Sources/SwiftDocC/Infrastructure/Link%20Resolution/ExternalPathHierarchyResolver.swift#L61-L63
[10]: https://github.com/swiftlang/swift-docc/blob/1b4a1850dd2785a8ebabded139ae0af3551bb029/Sources/SwiftDocC/Infrastructure/Link%20Resolution/PathHierarchy%2BError.swift#L115-L117

Author: anferbui

Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift

@@ -139,7 +139,12 @@ public struct LinkDestinationSummary: Codable, Equatable {
     public typealias DeclarationFragments = [DeclarationRenderSection.Token]
     /// The fragments for this symbol's declaration, or `nil` if the summarized element isn't a symbol.
     public let declarationFragments: DeclarationFragments?
-    
+
+    /// The abbreviated fragments for this symbol's declaration, or `nil` if the summarized element isn't a symbol.
+    ///
+    /// They are used for displaying in contexts where the full declaration fragments would be too verbose, like in the Topics section or the navigation index.
+    public let subHeadingDeclarationFragments: DeclarationFragments?
+
     /// Any previous URLs for this element.
     ///
     /// A web server can use this list of URLs to redirect to the current URL.
@@ -197,7 +202,13 @@ public struct LinkDestinationSummary: Codable, Equatable {
         ///
         /// If the summarized element has a declaration but the variant doesn't, this property will be `Optional.some(nil)`.
         public let declarationFragments: VariantValue<DeclarationFragments?>
-        
+
+        /// The abbreviated declaration of the variant or `nil` if the declaration is the same as the summarized element.
+        ///
+        /// They are used for displaying in contexts where the full declaration fragments would be too verbose, like in the Topics section or the navigation index.
+        /// If the summarized element has an abbreviated declaration but the variant doesn't, this property will be `Optional.some(nil)`.
+        public let subHeadingDeclarationFragments: VariantValue<DeclarationFragments?>
+
         /// Images that are used to represent the summarized element or `nil` if the images are the same as the summarized element.
         ///
         /// If the summarized element has an image but the variant doesn't, this property will be `Optional.some(nil)`.
@@ -215,6 +226,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
         ///   - taskGroups: The taskGroups of the variant or `nil` if the taskGroups is the same as the summarized element.
         ///   - usr: The precise symbol identifier of the variant or `nil` if the precise symbol identifier is the same as the summarized element.
         ///   - declarationFragments: The declaration of the variant or `nil` if the declaration is the same as the summarized element.
+        ///   - subHeadingDeclarationFragments: The abbreviated declaration of the variant or `nil` if the declaration is the same as the summarized element.
         ///   - topicImages: Images that are used to represent the summarized element or `nil` if the images are the same as the summarized element.
         public init(
             traits: [RenderNode.Variant.Trait],
@@ -226,6 +238,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
             taskGroups: VariantValue<[LinkDestinationSummary.TaskGroup]?> = nil,
             usr: VariantValue<String?> = nil,
             declarationFragments: VariantValue<LinkDestinationSummary.DeclarationFragments?> = nil,
+            subHeadingDeclarationFragments: VariantValue<LinkDestinationSummary.DeclarationFragments?> = nil,
             topicImages: VariantValue<[TopicImage]?> = nil
         ) {
             self.traits = traits
@@ -237,6 +250,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
             self.taskGroups = taskGroups
             self.usr = usr
             self.declarationFragments = declarationFragments
+            self.subHeadingDeclarationFragments = subHeadingDeclarationFragments
             self.topicImages = topicImages
         }
     }
@@ -258,6 +272,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
     ///   - taskGroups: The reference URLs of the summarized element's children, grouped by their task groups.
     ///   - usr: The unique, precise identifier for this symbol that you use to reference it across different systems, or `nil` if the summarized element isn't a symbol.
     ///   - declarationFragments: The fragments for this symbol's declaration, or `nil` if the summarized element isn't a symbol.
+    ///   - subHeadingDeclarationFragments: The abbreviated fragments for this symbol's declaration, or `nil` if the summarized element isn't a symbol.
     ///   - redirects: Any previous URLs for this element, or `nil` if this element has no previous URLs.
     ///   - topicImages: Images that are used to represent the summarized element, or `nil` if this element has no topic images.
     ///   - references: References used in the content of the summarized element, or `nil` if this element has no references to other content.
@@ -273,6 +288,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
         taskGroups: [LinkDestinationSummary.TaskGroup]? = nil,
         usr: String? = nil,
         declarationFragments: LinkDestinationSummary.DeclarationFragments? = nil,
+        subHeadingDeclarationFragments: LinkDestinationSummary.DeclarationFragments? = nil,
         redirects: [URL]? = nil,
         topicImages: [TopicImage]? = nil,
         references: [any RenderReference]? = nil,
@@ -289,6 +305,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
         self.taskGroups = taskGroups
         self.usr = usr
         self.declarationFragments = declarationFragments
+        self.subHeadingDeclarationFragments = subHeadingDeclarationFragments
         self.redirects = redirects
         self.topicImages = topicImages
         self.references = references
@@ -444,7 +461,11 @@ extension LinkDestinationSummary {
         let usr = symbol.externalIDVariants[summaryTrait] ?? symbol.externalID
         let declaration = (symbol.declarationVariants[summaryTrait] ?? symbol.declaration).renderDeclarationTokens()
         let language = documentationNode.sourceLanguage
-        
+        // Use the render metadata declaration fragments as the subheading declaration fragments.
+        // These have been derived from the symbol's original subheading declaration fragments as part of the rendering step.
+        // They are an abbreviated version of the declaration for display in Topic sections, the navigator, etc..
+        let subHeadingDeclaration = renderNode.metadata.fragmentsVariants.value(for: language)
+
         let variants: [Variant] = documentationNode.availableVariantTraits.compactMap { trait in
             // Skip the variant for the summarized elements source language.
             guard let interfaceLanguage = trait.interfaceLanguage, interfaceLanguage != documentationNode.sourceLanguage.id else {
@@ -460,6 +481,11 @@ extension LinkDestinationSummary {
             }
 
             let variantTraits = [RenderNode.Variant.Trait.interfaceLanguage(interfaceLanguage)]
+            
+            // Use the render metadata declaration fragments as the subheading declaration fragments.
+            // These have been derived from the symbol's original subheading declaration fragments as part of the rendering step.
+            // They are an abbreviated version of the declaration for display in Topic sections, the navigator, etc..
+            let subHeadingDeclarationVariant = renderNode.metadata.fragmentsVariants.value(for: variantTraits)
             return Variant(
                 traits: variantTraits,
                 kind: nilIfEqual(main: kind, variant: symbol.kindVariants[trait].map { DocumentationNode.kind(forKind: $0.identifier) }),
@@ -470,6 +496,7 @@ extension LinkDestinationSummary {
                 taskGroups: nilIfEqual(main: taskGroups, variant: taskGroupVariants[variantTraits]),
                 usr: nil, // The symbol variant uses the same USR
                 declarationFragments: nilIfEqual(main: declaration, variant: declarationVariant),
+                subHeadingDeclarationFragments: nilIfEqual(main: subHeadingDeclaration, variant: subHeadingDeclarationVariant),
                 topicImages: nil // The symbol variant doesn't currently have their own images
             )
         }
@@ -490,6 +517,7 @@ extension LinkDestinationSummary {
             taskGroups: taskGroups,
             usr: usr,
             declarationFragments: declaration,
+            subHeadingDeclarationFragments: subHeadingDeclaration,
             redirects: redirects,
             topicImages: topicImages.nilIfEmpty,
             references: references.nilIfEmpty,
@@ -574,6 +602,7 @@ extension LinkDestinationSummary {
         case kind, referenceURL, title, abstract, language, taskGroups, usr, availableLanguages, platforms, redirects, topicImages, references, variants
         case relativePresentationURL = "path"
         case declarationFragments = "fragments"
+        case subHeadingDeclarationFragments = "subheadingFragments"
     }
 
     public func encode(to encoder: any Encoder) throws {
@@ -589,6 +618,7 @@ extension LinkDestinationSummary {
         try container.encodeIfPresent(taskGroups, forKey: .taskGroups)
         try container.encodeIfPresent(usr, forKey: .usr)
         try container.encodeIfPresent(declarationFragments, forKey: .declarationFragments)
+        try container.encodeIfPresent(subHeadingDeclarationFragments, forKey: .subHeadingDeclarationFragments)
         try container.encodeIfPresent(redirects, forKey: .redirects)
         try container.encodeIfPresent(topicImages, forKey: .topicImages)
         try container.encodeIfPresent(references?.map { CodableRenderReference($0) }, forKey: .references)
@@ -626,6 +656,7 @@ extension LinkDestinationSummary {
         taskGroups = try container.decodeIfPresent([TaskGroup].self, forKey: .taskGroups)
         usr = try container.decodeIfPresent(String.self, forKey: .usr)
         declarationFragments = try container.decodeIfPresent(DeclarationFragments.self, forKey: .declarationFragments)
+        subHeadingDeclarationFragments = try container.decodeIfPresent(DeclarationFragments.self, forKey: .subHeadingDeclarationFragments)
         redirects = try container.decodeIfPresent([URL].self, forKey: .redirects)
         topicImages = try container.decodeIfPresent([TopicImage].self, forKey: .topicImages)
         references = try container.decodeIfPresent([CodableRenderReference].self, forKey: .references).map { decodedReferences in
@@ -641,6 +672,7 @@ extension LinkDestinationSummary.Variant {
         case traits, kind, title, abstract, language, usr, taskGroups, topicImages
         case relativePresentationURL = "path"
         case declarationFragments = "fragments"
+        case subHeadingDeclarationFragments = "subheadingFragments"
     }
 
     public func encode(to encoder: any Encoder) throws {
@@ -653,6 +685,7 @@ extension LinkDestinationSummary.Variant {
         try container.encodeIfPresent(language?.id, forKey: .language)
         try container.encodeIfPresent(usr, forKey: .usr)
         try container.encodeIfPresent(declarationFragments, forKey: .declarationFragments)
+        try container.encodeIfPresent(subHeadingDeclarationFragments, forKey: .subHeadingDeclarationFragments)
         try container.encodeIfPresent(taskGroups, forKey: .taskGroups)
         try container.encodeIfPresent(topicImages, forKey: .topicImages)
     }
@@ -692,6 +725,8 @@ extension LinkDestinationSummary.Variant {
         abstract = try container.decodeIfPresent(LinkDestinationSummary.Abstract?.self, forKey: .abstract)
         usr = try container.decodeIfPresent(String?.self, forKey: .usr)
         declarationFragments = try container.decodeIfPresent(LinkDestinationSummary.DeclarationFragments?.self, forKey: .declarationFragments)
+        subHeadingDeclarationFragments = try container
+            .decodeIfPresent(LinkDestinationSummary.DeclarationFragments?.self, forKey: .subHeadingDeclarationFragments)
         taskGroups = try container.decodeIfPresent([LinkDestinationSummary.TaskGroup]?.self, forKey: .taskGroups)
         topicImages = try container.decodeIfPresent([TopicImage]?.self, forKey: .topicImages)
     }

Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift

@@ -189,6 +189,11 @@ class ExternalLinkableTests: XCTestCase {
                 .init(text: " ", kind: .text, identifier: nil),
                 .init(text: "MyClass", kind: .identifier, identifier: nil),
             ])
+            XCTAssertEqual(summary.subHeadingDeclarationFragments, [
+                .init(text: "class", kind: .keyword, identifier: nil),
+                .init(text: " ", kind: .text, identifier: nil),
+                .init(text: "MyClass", kind: .identifier, identifier: nil),
+            ])
             XCTAssertNil(summary.topicImages)
             XCTAssertNil(summary.references)
 
@@ -230,6 +235,13 @@ class ExternalLinkableTests: XCTestCase {
                 .init(text: " : ", kind: .text, identifier: nil),
                 .init(text: "Hashable", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "p:hPP"),
             ])
+            XCTAssertEqual(summary.subHeadingDeclarationFragments, [
+                .init(text: "protocol", kind: .keyword, identifier: nil),
+                .init(text: " ", kind: .text, identifier: nil),
+                .init(text: "MyProtocol", kind: .identifier, identifier: nil),
+                .init(text: " : ", kind: .text, identifier: nil),
+                .init(text: "Hashable", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "p:hPP"),
+            ])
             XCTAssertNil(summary.topicImages)
             XCTAssertNil(summary.references)
 
@@ -265,6 +277,7 @@ class ExternalLinkableTests: XCTestCase {
                 .init(text: "...", kind: .text, identifier: nil),
                 .init(text: ")", kind: .text, identifier: nil)
             ])
+            XCTAssertNil(summary.subHeadingDeclarationFragments)
             XCTAssertNil(summary.topicImages)
             XCTAssertNil(summary.references)
 
@@ -303,6 +316,18 @@ class ExternalLinkableTests: XCTestCase {
                 .init(text: "Int", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "s:Si"),
                 .init(text: ")", kind: .text, identifier: nil)
             ])
+            XCTAssertEqual(summary.subHeadingDeclarationFragments, [
+                .init(text: "func", kind: .keyword, identifier: nil),
+                .init(text: " ", kind: .text, identifier: nil),
+                .init(text: "globalFunction", kind: .identifier, identifier: nil),
+                .init(text: "(", kind: .text, identifier: nil),
+                .init(text: "Data", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "s:10Foundation4DataV"),
+                .init(text: ", ", kind: .text, identifier: nil),
+                .init(text: "considering", kind: .identifier, identifier: nil),
+                .init(text: ": ", kind: .text, identifier: nil),
+                .init(text: "Int", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "s:Si"),
+                .init(text: ")", kind: .text, identifier: nil)
+            ])
             XCTAssertNil(summary.topicImages)
             XCTAssertNil(summary.references)