Use the subheading fragments to init the external entity

`LinkDestinationSummary` now provides information for both the full and abbreviated declaration fragments.

This commit adds the abbreviated declaration fragments to its counterpart type `OutOfProcessReferenceResolver.ResolvedInformation` [1], and uses them to initialise the external entity's `TopicRenderReference`. This is because the `TopicRenderReference` expects the abbreviated declaration fragments [2].

This results in the abbreviated declaration fragments correctly being used in the Topics and navigation index, rather than the full declaration fragments.

Fixes rdar://156488052.

[1]: https://github.com/swiftlang/swift-docc/blob/1b4a1850dd2785a8ebabded139ae0af3551bb029/Sources/SwiftDocC/Infrastructure/External%20Data/OutOfProcessReferenceResolver.swift#L559-L562
[2]: https://github.com/swiftlang/swift-docc/blob/1b4a1850dd2785a8ebabded139ae0af3551bb029/Sources/SwiftDocC/Model/Rendering/References/TopicRenderReference.swift#L50-L53

Author: anferbui

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

@@ -166,7 +166,8 @@ public class OutOfProcessReferenceResolver: ExternalDocumentationSource, GlobalE
             url: resolvedInformation.url.path,
             kind: kind,
             role: role,
-            fragments: resolvedInformation.declarationFragments?.declarationFragments.map { DeclarationRenderSection.Token(fragment: $0, identifier: nil) },
+            fragments: resolvedInformation.subHeadingDeclarationFragments?.declarationFragments
+                .map { DeclarationRenderSection.Token(fragment: $0, identifier: nil) },
             isBeta: resolvedInformation.isBeta,
             isDeprecated: (resolvedInformation.platforms ?? []).contains(where: { $0.deprecated != nil }),
             images: resolvedInformation.topicImages ?? []
@@ -182,7 +183,7 @@ public class OutOfProcessReferenceResolver: ExternalDocumentationSource, GlobalE
                     .init(traits: variant.traits, patch: [.replace(value: [.text(abstract)])])
                 )
             }
-            if let declarationFragments = variant.declarationFragments {
+            if let declarationFragments = variant.subHeadingDeclarationFragments {
                 renderReference.fragmentsVariants.variants.append(
                     .init(traits: variant.traits, patch: [.replace(value: declarationFragments?.declarationFragments.map { DeclarationRenderSection.Token(fragment: $0, identifier: nil) })])
                 )
@@ -577,7 +578,11 @@ extension OutOfProcessReferenceResolver {
         public let platforms: [PlatformAvailability]?
         /// Information about the resolved declaration fragments, if any.
         public let declarationFragments: DeclarationFragments?
-        
+        /// Information about the resolved abbreviated declaration fragments, if any.
+        ///
+        /// 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?
+
         // We use the real types here because they're Codable and don't have public member-wise initializers.
 
         /// Platform availability for a resolved symbol reference.
@@ -620,6 +625,7 @@ extension OutOfProcessReferenceResolver {
         ///   - 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.
+        ///   - subHeadingDeclarationFragments: The abbreviated resolved declaration fragments, if any.
         ///   - 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.
@@ -632,6 +638,7 @@ extension OutOfProcessReferenceResolver {
             availableLanguages: Set<SourceLanguage>,
             platforms: [PlatformAvailability]? = nil,
             declarationFragments: DeclarationFragments? = nil,
+            subHeadingDeclarationFragments: DeclarationFragments? = nil,
             topicImages: [TopicImage]? = nil,
             references: [any RenderReference]? = nil,
             variants: [Variant]? = nil
@@ -644,6 +651,7 @@ extension OutOfProcessReferenceResolver {
             self.availableLanguages = availableLanguages
             self.platforms = platforms
             self.declarationFragments = declarationFragments
+            self.subHeadingDeclarationFragments = subHeadingDeclarationFragments
             self.topicImages = topicImages
             self.references = references
             self.variants = variants
@@ -675,7 +683,12 @@ extension OutOfProcessReferenceResolver {
             ///
             /// If the resolver information has a declaration but the variant doesn't, this property will be `Optional.some(nil)`.
             public let declarationFragments: VariantValue<DeclarationFragments?>
-            
+            /// The abbreviated declaration fragments of the variant or `nil` if the declaration is the same as the resolved information.
+            ///
+            /// 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 resolver information has a declaration but the variant doesn't, this property will be `Optional.some(nil)`.
+            public let subHeadingDeclarationFragments: VariantValue<DeclarationFragments?>
+
             /// Creates a new resolved information variant with the values that are different from the resolved information values.
             ///
             /// - Parameters:
@@ -686,14 +699,16 @@ extension OutOfProcessReferenceResolver {
             ///   - abstract: The resolved (plain text) abstract.
             ///   - language: The resolved language.
             ///   - declarationFragments: The resolved declaration fragments, if any.
+            ///   - subHeadingDeclarationFragments: The resolved abbreviated declaration fragments, if any.
             public init(
                 traits: [RenderNode.Variant.Trait],
                 kind: VariantValue<DocumentationNode.Kind> = nil,
                 url: VariantValue<URL> = nil,
                 title: VariantValue<String> = nil,
                 abstract: VariantValue<String> = nil,
                 language: VariantValue<SourceLanguage> = nil,
-                declarationFragments: VariantValue<DeclarationFragments?> = nil
+                declarationFragments: VariantValue<DeclarationFragments?> = nil,
+                subHeadingDeclarationFragments: VariantValue<DeclarationFragments?> = nil
             ) {
                 self.traits = traits
                 self.kind = kind
@@ -702,6 +717,7 @@ extension OutOfProcessReferenceResolver {
                 self.abstract = abstract
                 self.language = language
                 self.declarationFragments = declarationFragments
+                self.subHeadingDeclarationFragments = subHeadingDeclarationFragments
             }
         }
     }
@@ -717,6 +733,7 @@ extension OutOfProcessReferenceResolver.ResolvedInformation {
         case availableLanguages
         case platforms
         case declarationFragments
+        case subHeadingDeclarationFragments
         case topicImages
         case references
         case variants
@@ -733,6 +750,8 @@ extension OutOfProcessReferenceResolver.ResolvedInformation {
         availableLanguages = try container.decode(Set<SourceLanguage>.self, forKey: .availableLanguages)
         platforms = try container.decodeIfPresent([OutOfProcessReferenceResolver.ResolvedInformation.PlatformAvailability].self, forKey: .platforms)
         declarationFragments = try container.decodeIfPresent(OutOfProcessReferenceResolver.ResolvedInformation.DeclarationFragments.self, forKey: .declarationFragments)
+        subHeadingDeclarationFragments = try container
+            .decodeIfPresent(OutOfProcessReferenceResolver.ResolvedInformation.DeclarationFragments.self, forKey: .subHeadingDeclarationFragments)
         topicImages = try container.decodeIfPresent([TopicImage].self, forKey: .topicImages)
         references = try container.decodeIfPresent([CodableRenderReference].self, forKey: .references).map { decodedReferences in
             decodedReferences.map(\.reference)
@@ -752,6 +771,7 @@ extension OutOfProcessReferenceResolver.ResolvedInformation {
         try container.encode(self.availableLanguages, forKey: .availableLanguages)
         try container.encodeIfPresent(self.platforms, forKey: .platforms)
         try container.encodeIfPresent(self.declarationFragments, forKey: .declarationFragments)
+        try container.encodeIfPresent(self.subHeadingDeclarationFragments, forKey: .subHeadingDeclarationFragments)
         try container.encodeIfPresent(self.topicImages, forKey: .topicImages)
         try container.encodeIfPresent(references?.map { CodableRenderReference($0) }, forKey: .references)
         try container.encodeIfPresent(self.variants, forKey: .variants)

Tests/SwiftDocCUtilitiesTests/OutOfProcessReferenceResolverTests.swift

@@ -70,6 +70,9 @@ class OutOfProcessReferenceResolverTests: XCTestCase {
             declarationFragments: .init(declarationFragments: [
                 .init(kind: .text, spelling: "declaration fragment", preciseIdentifier: nil)
             ]),
+            subHeadingDeclarationFragments: .init(declarationFragments: [
+                .init(kind: .text, spelling: "subheading declaration fragment", preciseIdentifier: nil)
+            ]),
             topicImages: nil,
             references: nil,
             variants: [
@@ -82,7 +85,10 @@ class OutOfProcessReferenceResolverTests: XCTestCase {
                     language: .init(name: "Language Name 2", id: "com.test.another-language.id"),
                     declarationFragments: .init(declarationFragments: [
                         .init(kind: .text, spelling: "variant declaration fragment", preciseIdentifier: nil)
-                    ])
+                    ]),
+                    subHeadingDeclarationFragments: .init(declarationFragments: [
+                        .init(kind: .text, spelling: "variant subheading declaration fragment", preciseIdentifier: nil)
+                    ]),
                 )
             ]
         )
@@ -120,7 +126,7 @@ class OutOfProcessReferenceResolverTests: XCTestCase {
         XCTAssertEqual(availableSourceLanguages[1], expectedLanguages[1])
         XCTAssertEqual(availableSourceLanguages[2], expectedLanguages[2])
 
-        XCTAssertEqual(entity.topicRenderReference.fragments, [.init(text: "declaration fragment", kind: .text, preciseIdentifier: nil)])
+        XCTAssertEqual(entity.topicRenderReference.fragments, [.init(text: "subheading declaration fragment", kind: .text, preciseIdentifier: nil)])
 
         let variantTraits = [RenderNode.Variant.Trait.interfaceLanguage("com.test.another-language.id")]
         XCTAssertEqual(entity.topicRenderReference.titleVariants.value(for: variantTraits), "Resolved Variant Title")
@@ -129,7 +135,7 @@ class OutOfProcessReferenceResolverTests: XCTestCase {
         let fragmentVariant = try XCTUnwrap(entity.topicRenderReference.fragmentsVariants.variants.first(where: { $0.traits == variantTraits }))
         XCTAssertEqual(fragmentVariant.patch.map(\.operation), [.replace])
         if case .replace(let variantFragment) = fragmentVariant.patch.first {
-            XCTAssertEqual(variantFragment, [.init(text: "variant declaration fragment", kind: .text, preciseIdentifier: nil)])
+            XCTAssertEqual(variantFragment, [.init(text: "variant subheading declaration fragment", kind: .text, preciseIdentifier: nil)])
         } else {
             XCTFail("Unexpected fragments variant patch")
         }
@@ -226,6 +232,9 @@ class OutOfProcessReferenceResolverTests: XCTestCase {
             declarationFragments: .init(declarationFragments: [
                 .init(kind: .text, spelling: "declaration fragment", preciseIdentifier: nil)
             ]),
+            subHeadingDeclarationFragments: .init(declarationFragments: [
+                .init(kind: .text, spelling: "subheading declaration fragment", preciseIdentifier: nil)
+            ]),
             topicImages: [
                 TopicImage(
                     type: .card,
@@ -260,6 +269,9 @@ class OutOfProcessReferenceResolverTests: XCTestCase {
                     language: .init(name: "Language Name 2", id: "com.test.another-language.id"),
                     declarationFragments: .init(declarationFragments: [
                         .init(kind: .text, spelling: "variant declaration fragment", preciseIdentifier: nil)
+                    ]),
+                    subHeadingDeclarationFragments: .init(declarationFragments: [
+                        .init(kind: .text, spelling: "variant subheading declaration fragment", preciseIdentifier: nil)
                     ])
                 )
             ]
@@ -288,7 +300,7 @@ class OutOfProcessReferenceResolverTests: XCTestCase {
         XCTAssertEqual(availableSourceLanguages[1], expectedLanguages[1])
         XCTAssertEqual(availableSourceLanguages[2], expectedLanguages[2])
 
-        XCTAssertEqual(entity.topicRenderReference.fragments, [.init(text: "declaration fragment", kind: .text, preciseIdentifier: nil)])
+        XCTAssertEqual(entity.topicRenderReference.fragments, [.init(text: "subheading declaration fragment", kind: .text, preciseIdentifier: nil)])
 
         let variantTraits = [RenderNode.Variant.Trait.interfaceLanguage("com.test.another-language.id")]
         XCTAssertEqual(entity.topicRenderReference.titleVariants.value(for: variantTraits), "Resolved Variant Title")
@@ -297,7 +309,7 @@ class OutOfProcessReferenceResolverTests: XCTestCase {
         let fragmentVariant = try XCTUnwrap(entity.topicRenderReference.fragmentsVariants.variants.first(where: { $0.traits == variantTraits }))
         XCTAssertEqual(fragmentVariant.patch.map(\.operation), [.replace])
         if case .replace(let variantFragment) = fragmentVariant.patch.first {
-            XCTAssertEqual(variantFragment, [.init(text: "variant declaration fragment", kind: .text, preciseIdentifier: nil)])
+            XCTAssertEqual(variantFragment, [.init(text: "variant subheading declaration fragment", kind: .text, preciseIdentifier: nil)])
         } else {
            XCTFail("Unexpected fragments variant patch")
         }