Use the abbreviated declaration fragments in 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].

However, currently `OutOfProcessReferenceResolver.ResolvedInformation. declarationFragments` is expecting the abbreviated declaration fragments, but we are storing the full fragments instead. [3]

Instead, we should be storing the abbreviated declaration fragments, which are stored as the `subHeading` of the symbol. [4] This subheading is further processed during the render node transformation phase [5], and stored as `renderNode.metadata.fragmentsVariants`.

This commit modifies `LinkDestinationSummary` such that its declaration fragments are the abbreviated declaration fragments  from `renderNode.metadata.fragmentsVariants` rather than the full declaration fragments.

The final result will be that declaration fragments for external links will behave the same as local links when referencing them in the Topics section. They will both now use the abbreviated declaration fragments.

[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/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift#L445
[4]: https://github.com/swiftlang/swift-docc-symbolkit/blob/ebe89c7da4cf03ded04cd708f3399087c6f2dad7/Sources/SymbolKit/SymbolGraph/Symbol/Names.swift#L28-L31

Author: anferbui

Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift

@@ -140,7 +140,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
 
     /// The rendered fragments of a symbol's declaration.
     public typealias DeclarationFragments = [DeclarationRenderSection.Token]
-    /// The fragments for this symbol's declaration, or `nil` if the summarized element isn't a symbol.
+    /// The abbreviated fragments for this symbol's declaration, or `nil` if the summarized element isn't a symbol.
     public let declarationFragments: DeclarationFragments?
 
     /// Any previous URLs for this element.
@@ -201,7 +201,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
         /// If the summarized element has a full name but the variant doesn't, this property will be `Optional.some(nil)`.
         public let fullName: VariantValue<String?>
 
-        /// The declaration of the variant or `nil` if the declaration is the same as the summarized element.
+        /// The abbreviated declaration of the variant or `nil` if the declaration is the same as the summarized element.
         ///
         /// If the summarized element has a declaration but the variant doesn't, this property will be `Optional.some(nil)`.
         public let declarationFragments: VariantValue<DeclarationFragments?>
@@ -224,7 +224,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.
         ///   - fullName: The full name of this symbol, derived from its full declaration fragments, 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.
+        ///   - declarationFragments: The abbreviated declaration of the variant or `nil` if the declaration is the same as the summarized element.
         public init(
             traits: [RenderNode.Variant.Trait],
             kind: VariantValue<DocumentationNode.Kind> = nil,
@@ -295,7 +295,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.
     ///   - fullName: The full name of this symbol, derived from its full declaration fragments, 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.
+    ///   - declarationFragments: 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.
@@ -483,17 +483,22 @@ extension LinkDestinationSummary {
         let abstract = renderSymbolAbstract(symbol.abstractVariants[summaryTrait] ?? symbol.abstract)
         let usr = symbol.externalIDVariants[summaryTrait] ?? symbol.externalID
         let fullName = symbol.fullName(for: summaryTrait)
-        let declaration = (symbol.declarationVariants[summaryTrait] ?? symbol.declaration).renderDeclarationTokens()
         let language = documentationNode.sourceLanguage
-        
+        // Use the abbreviated declaration fragments instead of the full declaration fragments.
+        // These have been derived from the symbol's subheading declaration fragments as part of rendering.
+        // We only want an abbreviated version of the declaration in the link summary (for display in Topic sections, the navigator, etc.).
+        // Otherwise, the declaration would be too verbose.
+        //
+        // However if no abbreviated declaration fragments are available, use the full declaration fragments instead.
+        // In this case, they are assumed to be the same.
+        let declaration = renderNode.metadata.fragmentsVariants.value(for: language) ?? (symbol.declarationVariants[summaryTrait] ?? symbol.declaration).renderDeclarationTokens()
+
         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 {
                 return nil
             }
 
-            let declarationVariant = symbol.declarationVariants[trait]?.renderDeclarationTokens()
-            
             let abstractVariant: Variant.VariantValue<Abstract?> = symbol.abstractVariants[trait].map { renderSymbolAbstract($0) }
 
             func nilIfEqual<Value: Equatable>(main: Value, variant: Value?) -> Value? {
@@ -502,6 +507,15 @@ extension LinkDestinationSummary {
 
             let fullNameVariant = symbol.fullName(for: trait)
             let variantTraits = [RenderNode.Variant.Trait.interfaceLanguage(interfaceLanguage)]
+            
+            // Use the abbreviated declaration fragments instead of the full declaration fragments.
+            // These have been derived from the symbol's subheading declaration fragments as part of rendering.
+            // We only want an abbreviated version of the declaration in the link summary (for display in Topic sections, the navigator, etc.).
+            // Otherwise, the declaration would be too verbose.
+            //
+            // However if no abbreviated declaration fragments are available, use the full declaration fragments instead.
+            // In this case, they are assumed to be the same.
+            let declarationVariant = renderNode.metadata.fragmentsVariants.value(for: variantTraits) ?? symbol.declarationVariants[trait]?.renderDeclarationTokens()
             return Variant(
                 traits: variantTraits,
                 kind: nilIfEqual(main: kind, variant: symbol.kindVariants[trait].map { DocumentationNode.kind(forKind: $0.identifier) }),

Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift

@@ -296,8 +296,6 @@ class LinkDestinationSummaryTests: XCTestCase {
                 .init(text: " ", kind: .text, identifier: nil),
                 .init(text: "globalFunction", kind: .identifier, identifier: nil),
                 .init(text: "(", kind: .text, identifier: nil),
-                .init(text: "_", 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),
@@ -530,10 +528,6 @@ class LinkDestinationSummaryTests: XCTestCase {
                 .init(text: " ", kind: .text, identifier: nil),
                 .init(text: "myStringFunction", kind: .identifier, identifier: nil),
                 .init(text: "(", kind: .text, identifier: nil),
-                .init(text: "_", kind: .externalParam, identifier: nil),
-                .init(text: " ", kind: .text, identifier: nil),
-                .init(text: "string", kind: .internalParam, identifier: nil),
-                .init(text: ": ", kind: .text, identifier: nil),
                 .init(text: "String", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "s:SS"),
                 .init(text: ") ", kind: .text, identifier: nil),
                 .init(text: "throws", kind: .keyword, identifier: nil),
@@ -551,17 +545,8 @@ class LinkDestinationSummaryTests: XCTestCase {
             XCTAssertEqual(variant.title, "myStringFunction:error:")
             XCTAssertEqual(variant.fullName, "+ (NSString *) myStringFunction: (NSString *)string error: (NSError **)error;")
             XCTAssertEqual(variant.declarationFragments, [
-                .init(text: "+ (", kind: .text, identifier: nil),
-                .init(text: "NSString", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "c:objc(cs)NSString"),
-                .init(text: " *) ", kind: .text, identifier: nil),
-                .init(text: "myStringFunction", kind: .identifier, identifier: nil),
-                .init(text: ": (", kind: .text, identifier: nil),
-                .init(text: "NSString", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "c:objc(cs)NSString"),
-                .init(text: " *)string ", kind: .text, identifier: nil),
-                .init(text: "error", kind: .identifier, identifier: nil),
-                .init(text: ": (", kind: .text, identifier: nil),
-                .init(text: "NSError", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "c:objc(cs)NSError"),
-                .init(text: " **)error;", kind: .text, identifier: nil)
+                .init(text: "+ ", kind: .text, identifier: nil),
+                .init(text: "myStringFunction:error:", kind: .identifier, identifier: nil)
             ])
 
             // Check variant content that is the same as the summarized element

Tests/SwiftDocCTests/Model/SemaToRenderNodeMultiLanguageTests.swift

@@ -556,7 +556,7 @@ class SemaToRenderNodeMixedLanguageTests: XCTestCase {
                 "myStringFunction:error:",
             ],
             referenceFragments: [
-                "typedef enum Foo : NSString {\n    ...\n} Foo;",
+                "+ myStringFunction:error:",
             ],
             failureMessage: { fieldName in
                 "Objective-C variant of 'MyArticle' article has unexpected content for '\(fieldName)'."

Tests/SwiftDocCTests/Test Bundles/MixedLanguageFramework.docc/symbol-graphs/clang/MixedLanguageFramework.symbols.json

@@ -366,46 +366,13 @@
           }
         ],
         "subHeading" : [
-          {
-            "kind" : "keyword",
-            "spelling" : "typedef"
-          },
           {
             "kind" : "text",
-            "spelling" : " "
-          },
-          {
-            "kind" : "keyword",
-            "spelling" : "enum"
-          },
-          {
-            "kind" : "text",
-            "spelling" : " "
+            "spelling" : "+ "
           },
           {
             "kind" : "identifier",
-            "spelling" : "Foo"
-          },
-          {
-            "kind" : "text",
-            "spelling" : " : "
-          },
-          {
-            "kind" : "typeIdentifier",
-            "spelling" : "NSString",
-            "preciseIdentifier": "c:@T@NSInteger"
-          },
-          {
-            "kind": "text",
-            "spelling": " {\n    ...\n} "
-          },
-          {
-            "kind": "identifier",
-            "spelling": "Foo"
-          },
-          {
-            "kind": "text",
-            "spelling": ";"
+            "spelling" : "myStringFunction:error:"
           }
         ]
       },
@@ -485,7 +452,7 @@
             "text" : "This is the foo's description."
           }
         ]
-      },
+      }
     },
     {
       "accessLevel" : "public",
@@ -570,7 +537,7 @@
           {
             "kind" : "typeIdentifier",
             "spelling" : "NSString",
-            "preciseIdentifier": "c:@T@NSInteger",
+            "preciseIdentifier": "c:@T@NSInteger"
           },
           {
             "kind": "text",
@@ -630,7 +597,7 @@
             "kind" : "identifier",
             "spelling" : "first"
           }
-        ],
+        ]
       },
       "pathComponents" : [
         "Foo",
@@ -677,7 +644,7 @@
             "kind" : "identifier",
             "spelling" : "fourth"
           }
-        ],
+        ]
       },
       "pathComponents" : [
         "Foo",
@@ -724,7 +691,7 @@
             "kind" : "identifier",
             "spelling" : "second"
           }
-        ],
+        ]
       },
       "pathComponents" : [
         "Foo",
@@ -771,7 +738,7 @@
             "kind" : "identifier",
             "spelling" : "third"
           }
-        ],
+        ]
       },
       "pathComponents" : [
         "Foo",