Rename to subheadingDeclarationFragments for clarity

anferbui · anferbui · commit fbc7a8a222c2 · 2025-09-26T14:27:48.000+01:00
`declarationFragments` was not descriptive enough about the contents of the property, so renamed to `subheadingDeclarationFragments` and deprecated `declarationFragments` for backwards compatibility.

The JSON encoding key is kept the same (`fragments`) for backwards compatibility.
diff --git a/Sources/SwiftDocC/Infrastructure/Link Resolution/ExternalPathHierarchyResolver.swift b/Sources/SwiftDocC/Infrastructure/Link Resolution/ExternalPathHierarchyResolver.swift
@@ -171,7 +171,7 @@ 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: navigatorTitle)
         
         for variant in variants {
@@ -182,7 +182,7 @@ 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.navigatorTitle {
diff --git a/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift b/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift
diff --git a/Tests/SwiftDocCTests/Indexing/ExternalRenderNodeTests.swift b/Tests/SwiftDocCTests/Indexing/ExternalRenderNodeTests.swift
@@ -180,13 +180,13 @@ class ExternalRenderNodeTests: XCTestCase {
             title: swiftTitle,
             availableLanguages: [.swift, .objectiveC],
             usr: "some-unique-symbol-id",
-            declarationFragments: swiftFragments,
+            subheadingDeclarationFragments: swiftFragments,
             variants: [
                 .init(
                     traits: [.interfaceLanguage(SourceLanguage.objectiveC.id)],
                     language: .objectiveC,
                     title: objcTitle,
-                    declarationFragments: objcFragments
+                    subheadingDeclarationFragments: objcFragments
                 )
             ]
         )
@@ -467,13 +467,13 @@ class ExternalRenderNodeTests: XCTestCase {
             availableLanguages: [.swift, .objectiveC],
             platforms: [.init(name: "Platform name", introduced: "1.2.3", isBeta: true)],
             usr: "some-unique-symbol-id",
-            declarationFragments: swiftFragments,
+            subheadingDeclarationFragments: swiftFragments,
             variants: [
                 .init(
                     traits: [.interfaceLanguage(SourceLanguage.objectiveC.id)],
                     language: .objectiveC,
                     title: objcTitle,
-                    declarationFragments: objcFragments
+                    subheadingDeclarationFragments: objcFragments
                 )
             ]
         )
diff --git a/Tests/SwiftDocCTests/Infrastructure/ExternalReferenceResolverTests.swift b/Tests/SwiftDocCTests/Infrastructure/ExternalReferenceResolverTests.swift
@@ -45,7 +45,7 @@ class ExternalReferenceResolverTests: XCTestCase {
                 referenceURL: reference.url,
                 title: resolvedEntityTitle,
                 availableLanguages: [resolvedEntityLanguage],
-                declarationFragments: resolvedEntityDeclarationFragments?.declarationFragments.map { .init(fragment: $0, identifier: nil) },
+                subheadingDeclarationFragments: resolvedEntityDeclarationFragments?.declarationFragments.map { .init(fragment: $0, identifier: nil) },
                 variants: []
             )
         }
diff --git a/Tests/SwiftDocCTests/Infrastructure/TestExternalReferenceResolvers.swift b/Tests/SwiftDocCTests/Infrastructure/TestExternalReferenceResolvers.swift
@@ -93,7 +93,7 @@ class TestMultiResultExternalReferenceResolver: ExternalDocumentationSource {
             title: entityInfo.title,
             availableLanguages: [entityInfo.language],
             platforms: entityInfo.platforms,
-            declarationFragments: entityInfo.declarationFragments?.declarationFragments.map { .init(fragment: $0, identifier: nil) },
+            subheadingDeclarationFragments: entityInfo.declarationFragments?.declarationFragments.map { .init(fragment: $0, identifier: nil) },
             navigatorTitle: entityInfo.navigatorTitle?.declarationFragments.map { .init(fragment: $0, identifier: nil) },
             topicImages: entityInfo.topicImages?.map(\.0),
             references: entityInfo.topicImages?.map { topicImage, altText in
diff --git a/Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift b/Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift
@@ -114,7 +114,7 @@ class LinkDestinationSummaryTests: XCTestCase {
         XCTAssertEqual(pageSummary.redirects, nil)
         XCTAssertNil(pageSummary.usr, "Only symbols have USRs")
         XCTAssertNil(pageSummary.plainTextDeclaration, "Only symbols have a plain text declaration")
-        XCTAssertNil(pageSummary.declarationFragments, "Only symbols have declaration fragments")
+        XCTAssertNil(pageSummary.subheadingDeclarationFragments, "Only symbols have subheading declaration fragments")
         XCTAssertNil(pageSummary.navigatorTitle, "Only symbols have navigator titles")
         XCTAssertNil(pageSummary.abstract, "There is no text to use as an abstract for the tutorial page")
         XCTAssertNil(pageSummary.topicImages, "The tutorial page doesn't have any topic images")
@@ -134,7 +134,7 @@ class LinkDestinationSummaryTests: XCTestCase {
         ])
         XCTAssertNil(sectionSummary.usr, "Only symbols have USRs")
         XCTAssertNil(sectionSummary.plainTextDeclaration, "Only symbols have a plain text declaration")
-        XCTAssertNil(sectionSummary.declarationFragments, "Only symbols have declaration fragments")
+        XCTAssertNil(sectionSummary.subheadingDeclarationFragments, "Only symbols have subheading declaration fragments")
         XCTAssertNil(sectionSummary.navigatorTitle, "Only symbols have navigator titles")
         XCTAssertEqual(sectionSummary.abstract, [
             .text("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt"),
@@ -185,7 +185,7 @@ class LinkDestinationSummaryTests: XCTestCase {
             XCTAssertEqual(summary.platforms, renderNode.metadata.platforms)
             XCTAssertEqual(summary.usr, "s:5MyKit0A5ClassC")
             XCTAssertEqual(summary.plainTextDeclaration, "class MyClass")
-            XCTAssertEqual(summary.declarationFragments, [
+            XCTAssertEqual(summary.subheadingDeclarationFragments, [
                 .init(text: "class", kind: .keyword, identifier: nil),
                 .init(text: " ", kind: .text, identifier: nil),
                 .init(text: "MyClass", kind: .identifier, identifier: nil),
@@ -228,7 +228,7 @@ class LinkDestinationSummaryTests: XCTestCase {
             XCTAssertEqual(summary.platforms, renderNode.metadata.platforms)
             XCTAssertEqual(summary.usr, "s:5MyKit0A5ProtocolP")
             XCTAssertEqual(summary.plainTextDeclaration, "protocol MyProtocol : Hashable")
-            XCTAssertEqual(summary.declarationFragments, [
+            XCTAssertEqual(summary.subheadingDeclarationFragments, [
                 .init(text: "protocol", kind: .keyword, identifier: nil),
                 .init(text: " ", kind: .text, identifier: nil),
                 .init(text: "MyProtocol", kind: .identifier, identifier: nil),
@@ -263,7 +263,7 @@ class LinkDestinationSummaryTests: XCTestCase {
             XCTAssertEqual(summary.platforms, renderNode.metadata.platforms)
             XCTAssertEqual(summary.usr, "s:5MyKit0A5ClassC10myFunctionyyF")
             XCTAssertEqual(summary.plainTextDeclaration, "func myFunction(for name...)")
-            XCTAssertEqual(summary.declarationFragments, [
+            XCTAssertEqual(summary.subheadingDeclarationFragments, [
                 .init(text: "func", kind: .keyword, identifier: nil),
                 .init(text: " ", kind: .text, identifier: nil),
                 .init(text: "myFunction", kind: .identifier, identifier: nil),
@@ -300,7 +300,7 @@ class LinkDestinationSummaryTests: XCTestCase {
             XCTAssertEqual(summary.platforms, renderNode.metadata.platforms)
             XCTAssertEqual(summary.usr, "s:5MyKit14globalFunction_11consideringy10Foundation4DataV_SitF")
             XCTAssertEqual(summary.plainTextDeclaration, "func globalFunction(_: Data, considering: Int)")
-            XCTAssertEqual(summary.declarationFragments, [
+            XCTAssertEqual(summary.subheadingDeclarationFragments, [
                 .init(text: "func", kind: .keyword, identifier: nil),
                 .init(text: " ", kind: .text, identifier: nil),
                 .init(text: "globalFunction", kind: .identifier, identifier: nil),
@@ -368,7 +368,7 @@ class LinkDestinationSummaryTests: XCTestCase {
             XCTAssertEqual(summary.platforms, renderNode.metadata.platforms)
             XCTAssertEqual(summary.usr, "s:5MyKit0A5ClassC10myFunctionyyF")
             XCTAssertEqual(summary.plainTextDeclaration, "func myFunction(for name...)")
-            XCTAssertEqual(summary.declarationFragments, [
+            XCTAssertEqual(summary.subheadingDeclarationFragments, [
                 .init(text: "func", kind: .keyword, identifier: nil),
                 .init(text: " ", kind: .text, identifier: nil),
                 .init(text: "myFunction", kind: .identifier, identifier: nil),
@@ -482,7 +482,7 @@ class LinkDestinationSummaryTests: XCTestCase {
             XCTAssertEqual(summary.platforms, renderNode.metadata.platforms)
             XCTAssertEqual(summary.usr, "c:objc(cs)Bar")
             XCTAssertEqual(summary.plainTextDeclaration, "class Bar")
-            XCTAssertEqual(summary.declarationFragments, [
+            XCTAssertEqual(summary.subheadingDeclarationFragments, [
                 .init(text: "class", kind: .keyword, identifier: nil),
                 .init(text: " ", kind: .text, identifier: nil),
                 .init(text: "Bar", kind: .identifier, identifier: nil)
@@ -499,7 +499,7 @@ class LinkDestinationSummaryTests: XCTestCase {
             // Check variant content that is different
             XCTAssertEqual(variant.language, .objectiveC)
             XCTAssertEqual(variant.plainTextDeclaration, "@interface Bar : NSObject")
-            XCTAssertEqual(variant.declarationFragments, [
+            XCTAssertEqual(variant.subheadingDeclarationFragments, [
                 .init(text: "@interface", kind: .keyword, identifier: nil),
                 .init(text: " ", kind: .text, identifier: nil),
                 .init(text: "Bar", kind: .identifier, identifier: nil),
@@ -549,7 +549,7 @@ class LinkDestinationSummaryTests: XCTestCase {
             XCTAssertEqual(summary.platforms, renderNode.metadata.platforms)
             XCTAssertEqual(summary.usr, "c:objc(cs)Bar(cm)myStringFunction:error:")
             XCTAssertEqual(summary.plainTextDeclaration, "class func myStringFunction(_ string: String) throws -> String")
-            XCTAssertEqual(summary.declarationFragments, [
+            XCTAssertEqual(summary.subheadingDeclarationFragments, [
                 .init(text: "class", kind: .keyword, identifier: nil),
                 .init(text: " ", kind: .text, identifier: nil),
                 .init(text: "func", kind: .keyword, identifier: nil),
@@ -575,7 +575,7 @@ class LinkDestinationSummaryTests: XCTestCase {
             XCTAssertEqual(variant.language, .objectiveC)
             XCTAssertEqual(variant.title, "myStringFunction:error:")
             XCTAssertEqual(variant.plainTextDeclaration, "+ (NSString *) myStringFunction: (NSString *)string error: (NSError **)error;")
-            XCTAssertEqual(variant.declarationFragments, [
+            XCTAssertEqual(variant.subheadingDeclarationFragments, [
                 .init(text: "+ ", kind: .text, identifier: nil),
                 .init(text: "myStringFunction:error:", kind: .identifier, identifier: nil)
             ])
@@ -713,7 +713,7 @@ class LinkDestinationSummaryTests: XCTestCase {
         XCTAssertEqual(decoded.title, "ClassName")
         XCTAssertEqual(decoded.abstract?.plainText, "A brief explanation of my class.")
         XCTAssertEqual(decoded.relativePresentationURL.absoluteString, "documentation/MyKit/ClassName")
-        XCTAssertEqual(decoded.declarationFragments, [
+        XCTAssertEqual(decoded.subheadingDeclarationFragments, [
             .init(text: "class", kind: .keyword, identifier: nil),
             .init(text: " ", kind: .text, identifier: nil),
             .init(text: "ClassName", kind: .identifier, identifier: nil),
diff --git a/Tests/SwiftDocCTests/OutOfProcessReferenceResolverV2Tests.swift b/Tests/SwiftDocCTests/OutOfProcessReferenceResolverV2Tests.swift
@@ -85,7 +85,7 @@ class OutOfProcessReferenceResolverV2Tests: XCTestCase {
                 .init(name: "secondOS", introduced: "4.5.6", isBeta: false),
             ],
             usr: "some-unique-symbol-id",
-            declarationFragments: .init([
+            subheadingDeclarationFragments: .init([
                 .init(text: "struct", kind: .keyword, preciseIdentifier: nil),
                 .init(text: " ", kind: .text, preciseIdentifier: nil),
                 .init(text: "declaration fragment", kind: .identifier, preciseIdentifier: nil),
@@ -127,7 +127,7 @@ class OutOfProcessReferenceResolverV2Tests: XCTestCase {
                         .text(" and a link: "),
                         .reference(identifier: linkedVariantReference, isActive: true, overridingTitle: nil, overridingTitleInlineContent: nil)
                     ],
-                    declarationFragments: .init([
+                    subheadingDeclarationFragments: .init([
                         .init(text: "variant declaration fragment", kind: .text, preciseIdentifier: nil)
                     ])
                 )
@@ -341,12 +341,6 @@ class OutOfProcessReferenceResolverV2Tests: XCTestCase {
                 .text("."),
             ],
             availableLanguages: [.swift],
-            platforms: nil,
-            taskGroups: nil,
-            usr: nil,
-            declarationFragments: nil,
-            redirects: nil,
-            topicImages: nil,
             references: [originalLinkedImage, originalLinkedTopic],
             variants: []
         )
diff --git a/Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift b/Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift
@@ -3218,7 +3218,7 @@ private extension LinkDestinationSummary {
             platforms: platforms,
             taskGroups: taskGroups,
             usr: usr,
-            declarationFragments: nil,
+            subheadingDeclarationFragments: nil,
             redirects: redirects,
             topicImages: topicImages,
             references: references,

Original file line number	Diff line number	Diff line change
`@@ -180,13 +180,13 @@ class ExternalRenderNodeTests: XCTestCase {`
`180`	`180`	`title: swiftTitle,`
`181`	`181`	`availableLanguages: [.swift, .objectiveC],`
`182`	`182`	`usr: "some-unique-symbol-id",`
`183`		`- declarationFragments: swiftFragments,`
	`183`	`+ subheadingDeclarationFragments: swiftFragments,`
`184`	`184`	`variants: [`
`185`	`185`	`.init(`
`186`	`186`	`traits: [.interfaceLanguage(SourceLanguage.objectiveC.id)],`
`187`	`187`	`language: .objectiveC,`
`188`	`188`	`title: objcTitle,`
`189`		`- declarationFragments: objcFragments`
	`189`	`+ subheadingDeclarationFragments: objcFragments`
`190`	`190`	`)`
`191`	`191`	`]`
`192`	`192`	`)`
`@@ -467,13 +467,13 @@ class ExternalRenderNodeTests: XCTestCase {`
`467`	`467`	`availableLanguages: [.swift, .objectiveC],`
`468`	`468`	`platforms: [.init(name: "Platform name", introduced: "1.2.3", isBeta: true)],`
`469`	`469`	`usr: "some-unique-symbol-id",`
`470`		`- declarationFragments: swiftFragments,`
	`470`	`+ subheadingDeclarationFragments: swiftFragments,`
`471`	`471`	`variants: [`
`472`	`472`	`.init(`
`473`	`473`	`traits: [.interfaceLanguage(SourceLanguage.objectiveC.id)],`
`474`	`474`	`language: .objectiveC,`
`475`	`475`	`title: objcTitle,`
`476`		`- declarationFragments: objcFragments`
	`476`	`+ subheadingDeclarationFragments: objcFragments`
`477`	`477`	`)`
`478`	`478`	`]`
`479`	`479`	`)`
Original file line number	Diff line number	Diff line change
`@@ -45,7 +45,7 @@ class ExternalReferenceResolverTests: XCTestCase {`
`45`	`45`	`referenceURL: reference.url,`
`46`	`46`	`title: resolvedEntityTitle,`
`47`	`47`	`availableLanguages: [resolvedEntityLanguage],`
`48`		`- declarationFragments: resolvedEntityDeclarationFragments?.declarationFragments.map { .init(fragment: $0, identifier: nil) },`
	`48`	`+ subheadingDeclarationFragments: resolvedEntityDeclarationFragments?.declarationFragments.map { .init(fragment: $0, identifier: nil) },`
`49`	`49`	`variants: []`
`50`	`50`	`)`
`51`	`51`	`}`