Add full (symbol) name to LinkDestinationSummary

The only use-case for storing the full declaration fragments in `LinkDestinationSummary` rather than the shortened declaration fragments intended for display, is to derive the full name of the symbol in diagnostics [1] [2].  We have a number of tests [3] which verify that the diagnostic emitted when a symbol is referenced locally is the same as when the symbol is referenced externally.

However, we want to stop storing the full declaration fragments in favour of the shortened ones because:
- the full fragments are never displayed when referenced externally, as they are too long
- the full fragments take up additionally storage space, and encoding/decoding time, to only be used to derive the full name of the symbol

This commit updates the logic such that, we pre-derive the full name of the symbol from its declaration fragments, and then store that as part of `LinkDestinationSummary`, so that in a subsequent commit we can stop storing the full declaration fragments and store only the shortened ones instead.

The diagnostic logic has also been updated to use the new field rather than the full declaration fragments.

[1]: https://github.com/swiftlang/swift-docc/blob/1b4a1850dd2785a8ebabded139ae0af3551bb029/Sources/SwiftDocC/Infrastructure/Link%20Resolution/ExternalPathHierarchyResolver.swift#L61-L63
[2]: https://github.com/swiftlang/swift-docc/blob/1b4a1850dd2785a8ebabded139ae0af3551bb029/Sources/SwiftDocC/Infrastructure/Link%20Resolution/PathHierarchy%2BError.swift#L115-L117
[3]: https://github.com/swiftlang/swift-docc/blob/9413c599817abc9dd4f8feeed57a998b19a05a6f/Tests/SwiftDocCTests/Infrastructure/ExternalPathHierarchyResolverTests.swift#L907-L918

Author: anferbui

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 fullName = summary.fullName {
+                return fullName
             }
             if let variant = summary.variants.first(where: { $0.traits.contains(.interfaceLanguage(symbolID.interfaceLanguage)) }),
-               let fragments = variant.declarationFragments ?? summary.declarationFragments
+               let fullName = variant.fullName ?? summary.fullName
             {
-                return fragments.plainTextDeclaration()
+                return fullName
             }
         }
         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 {

Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift

@@ -135,6 +135,9 @@ public struct LinkDestinationSummary: Codable, Equatable {
     /// 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.
     public let usr: String?
 
+    /// The full name of this symbol, derived from its full declaration fragments, or `nil` if the summarized element isn't a symbol.
+    public let fullName: String?
+    
     /// 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.
@@ -193,6 +196,11 @@ public struct LinkDestinationSummary: Codable, Equatable {
         /// If the summarized element has a precise symbol identifier but the variant doesn't, this property will be `Optional.some(nil)`.
         public let usr: VariantValue<String?>
 
+        /// 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.
+        ///
+        /// 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.
         ///
         /// If the summarized element has a declaration but the variant doesn't, this property will be `Optional.some(nil)`.
@@ -215,6 +223,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
         ///   - abstract: The abstract of the variant or `nil` if the abstract is the same as the summarized element.
         ///   - 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.
         public init(
             traits: [RenderNode.Variant.Trait],
@@ -225,6 +234,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
             abstract: VariantValue<LinkDestinationSummary.Abstract?> = nil,
             taskGroups: VariantValue<[LinkDestinationSummary.TaskGroup]?> = nil,
             usr: VariantValue<String?> = nil,
+            fullName: VariantValue<String?> = nil,
             declarationFragments: VariantValue<LinkDestinationSummary.DeclarationFragments?> = nil
         ) {
             self.traits = traits
@@ -235,10 +245,11 @@ public struct LinkDestinationSummary: Codable, Equatable {
             self.abstract = abstract
             self.taskGroups = taskGroups
             self.usr = usr
+            self.fullName = fullName
             self.declarationFragments = declarationFragments
         }
 
-        @available(*, deprecated, renamed: "init(traits:kind:language:relativePresentationURL:title:abstract:taskGroups:usr:declarationFragments:)", message: "Use `init(traits:kind:language:relativePresentationURL:title:abstract:taskGroups:usr:declarationFragments:)` instead. `TopicRenderReference` doesn't support variant specific topic images. This property will be removed after 6.3 is released")
+        @available(*, deprecated, renamed: "init(traits:kind:language:relativePresentationURL:title:abstract:taskGroups:usr:fullName:declarationFragments:)", message: "Use `init(traits:kind:language:relativePresentationURL:title:abstract:taskGroups:usr:fullName:declarationFragments:)` instead. `TopicRenderReference` doesn't support variant specific topic images. This property will be removed after 6.3 is released")
         public init(
             traits: [RenderNode.Variant.Trait],
             kind: VariantValue<DocumentationNode.Kind> = nil,
@@ -248,6 +259,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
             abstract: VariantValue<LinkDestinationSummary.Abstract?> = nil,
             taskGroups: VariantValue<[LinkDestinationSummary.TaskGroup]?> = nil,
             usr: VariantValue<String?> = nil,
+            fullName: VariantValue<String?> = nil,
             declarationFragments: VariantValue<LinkDestinationSummary.DeclarationFragments?> = nil,
             topicImages: VariantValue<[TopicImage]?> = nil
         ) {
@@ -260,6 +272,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
                 abstract: abstract,
                 taskGroups: taskGroups,
                 usr: usr,
+                fullName: fullName,
                 declarationFragments: declarationFragments
             )
         }
@@ -281,6 +294,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
     ///   - platforms: Information about the platforms for which the summarized element is available.
     ///   - 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.
     ///   - 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.
@@ -296,6 +310,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
         platforms: [LinkDestinationSummary.PlatformAvailability]? = nil,
         taskGroups: [LinkDestinationSummary.TaskGroup]? = nil,
         usr: String? = nil,
+        fullName: String? = nil,
         declarationFragments: LinkDestinationSummary.DeclarationFragments? = nil,
         redirects: [URL]? = nil,
         topicImages: [TopicImage]? = nil,
@@ -312,6 +327,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
         self.platforms = platforms
         self.taskGroups = taskGroups
         self.usr = usr
+        self.fullName = fullName
         self.declarationFragments = declarationFragments
         self.redirects = redirects
         self.topicImages = topicImages
@@ -466,6 +482,7 @@ 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
 
@@ -483,6 +500,7 @@ extension LinkDestinationSummary {
                 return main == variant ? nil : variant
             }
 
+            let fullNameVariant = symbol.fullName(for: trait)
             let variantTraits = [RenderNode.Variant.Trait.interfaceLanguage(interfaceLanguage)]
             return Variant(
                 traits: variantTraits,
@@ -493,6 +511,7 @@ extension LinkDestinationSummary {
                 abstract: nilIfEqual(main: abstract, variant: abstractVariant),
                 taskGroups: nilIfEqual(main: taskGroups, variant: taskGroupVariants[variantTraits]),
                 usr: nil, // The symbol variant uses the same USR
+                fullName: nilIfEqual(main: fullName, variant: fullNameVariant),
                 declarationFragments: nilIfEqual(main: declaration, variant: declarationVariant)
             )
         }
@@ -512,6 +531,7 @@ extension LinkDestinationSummary {
             platforms: platforms,
             taskGroups: taskGroups,
             usr: usr,
+            fullName: fullName,
             declarationFragments: declaration,
             redirects: redirects,
             topicImages: topicImages.nilIfEmpty,
@@ -594,7 +614,7 @@ extension LinkDestinationSummary {
 // Add Codable methods—which include an initializer—in an extension so that it doesn't override the member-wise initializer.
 extension LinkDestinationSummary {
     enum CodingKeys: String, CodingKey {
-        case kind, referenceURL, title, abstract, language, taskGroups, usr, availableLanguages, platforms, redirects, topicImages, references, variants
+        case kind, referenceURL, title, abstract, language, taskGroups, usr, availableLanguages, platforms, redirects, topicImages, references, variants, fullName
         case relativePresentationURL = "path"
         case declarationFragments = "fragments"
     }
@@ -626,6 +646,7 @@ extension LinkDestinationSummary {
         try container.encodeIfPresent(platforms, forKey: .platforms)
         try container.encodeIfPresent(taskGroups, forKey: .taskGroups)
         try container.encodeIfPresent(usr, forKey: .usr)
+        try container.encodeIfPresent(fullName, forKey: .fullName)
         try container.encodeIfPresent(declarationFragments, forKey: .declarationFragments)
         try container.encodeIfPresent(redirects, forKey: .redirects)
         try container.encodeIfPresent(topicImages, forKey: .topicImages)
@@ -682,6 +703,7 @@ extension LinkDestinationSummary {
         platforms = try container.decodeIfPresent([AvailabilityRenderItem].self, forKey: .platforms)
         taskGroups = try container.decodeIfPresent([TaskGroup].self, forKey: .taskGroups)
         usr = try container.decodeIfPresent(String.self, forKey: .usr)
+        fullName = try container.decodeIfPresent(String.self, forKey: .fullName)
         declarationFragments = try container.decodeIfPresent(DeclarationFragments.self, forKey: .declarationFragments)
         redirects = try container.decodeIfPresent([URL].self, forKey: .redirects)
         topicImages = try container.decodeIfPresent([TopicImage].self, forKey: .topicImages)
@@ -695,7 +717,7 @@ extension LinkDestinationSummary {
 
 extension LinkDestinationSummary.Variant {
     enum CodingKeys: String, CodingKey {
-        case traits, kind, title, abstract, language, usr, taskGroups
+        case traits, kind, title, abstract, language, usr, taskGroups, fullName
         case relativePresentationURL = "path"
         case declarationFragments = "fragments"
     }
@@ -721,6 +743,7 @@ extension LinkDestinationSummary.Variant {
             }
         }
         try container.encodeIfPresent(usr, forKey: .usr)
+        try container.encodeIfPresent(fullName, forKey: .fullName)
         try container.encodeIfPresent(declarationFragments, forKey: .declarationFragments)
         try container.encodeIfPresent(taskGroups, forKey: .taskGroups)
     }
@@ -762,6 +785,7 @@ extension LinkDestinationSummary.Variant {
         title = try container.decodeIfPresent(String.self, forKey: .title)
         abstract = try container.decodeIfPresent(LinkDestinationSummary.Abstract?.self, forKey: .abstract)
         usr = try container.decodeIfPresent(String?.self, forKey: .usr)
+        fullName = try container.decodeIfPresent(String?.self, forKey: .fullName)
         declarationFragments = try container.decodeIfPresent(LinkDestinationSummary.DeclarationFragments?.self, forKey: .declarationFragments)
         taskGroups = try container.decodeIfPresent([LinkDestinationSummary.TaskGroup]?.self, forKey: .taskGroups)
     }
@@ -871,3 +895,16 @@ private extension Collection {
         isEmpty ? nil : self
     }
 }
+
+private extension Sequence<DeclarationRenderSection.Token> {
+    func plainTextDeclaration() -> String {
+        return self.map(\.text).joined().split(whereSeparator: { $0.isWhitespace || $0.isNewline }).joined(separator: " ")
+    }
+}
+
+private extension Symbol {
+    func fullName(for trait: DocumentationDataVariantsTrait) -> String? {
+        let fullDeclaration = (self.declarationVariants[trait] ?? self.declaration).renderDeclarationTokens()
+        return fullDeclaration?.plainTextDeclaration()
+    }
+}