Skip to content

Commit 18ba146

Browse files
anferbuianferbui
committed
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
1 parent 1b8e7ca commit 18ba146

File tree

4 files changed

+33
-67
lines changed

4 files changed

+33
-67
lines changed

‎Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift‎

Lines changed: 22 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
140140

141141
/// The rendered fragments of a symbol's declaration.
142142
public typealias DeclarationFragments = [DeclarationRenderSection.Token]
143-
/// The fragments for this symbol's declaration, or `nil` if the summarized element isn't a symbol.
143+
/// The abbreviated fragments for this symbol's declaration, or `nil` if the summarized element isn't a symbol.
144144
public let declarationFragments: DeclarationFragments?
145145

146146
/// Any previous URLs for this element.
@@ -201,7 +201,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
201201
/// If the summarized element has a full name but the variant doesn't, this property will be `Optional.some(nil)`.
202202
public let fullName: VariantValue<String?>
203203

204-
/// The declaration of the variant or `nil` if the declaration is the same as the summarized element.
204+
/// The abbreviated declaration of the variant or `nil` if the declaration is the same as the summarized element.
205205
///
206206
/// If the summarized element has a declaration but the variant doesn't, this property will be `Optional.some(nil)`.
207207
public let declarationFragments: VariantValue<DeclarationFragments?>
@@ -224,7 +224,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
224224
/// - taskGroups: The taskGroups of the variant or `nil` if the taskGroups is the same as the summarized element.
225225
/// - usr: The precise symbol identifier of the variant or `nil` if the precise symbol identifier is the same as the summarized element.
226226
/// - 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.
227-
/// - declarationFragments: The declaration of the variant or `nil` if the declaration is the same as the summarized element.
227+
/// - declarationFragments: The abbreviated declaration of the variant or `nil` if the declaration is the same as the summarized element.
228228
public init(
229229
traits: [RenderNode.Variant.Trait],
230230
kind: VariantValue<DocumentationNode.Kind> = nil,
@@ -295,7 +295,7 @@ public struct LinkDestinationSummary: Codable, Equatable {
295295
/// - taskGroups: The reference URLs of the summarized element's children, grouped by their task groups.
296296
/// - 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.
297297
/// - fullName: The full name of this symbol, derived from its full declaration fragments, or `nil` if the summarized element isn't a symbol.
298-
/// - declarationFragments: The fragments for this symbol's declaration, or `nil` if the summarized element isn't a symbol.
298+
/// - declarationFragments: The abbreviated fragments for this symbol's declaration, or `nil` if the summarized element isn't a symbol.
299299
/// - redirects: Any previous URLs for this element, or `nil` if this element has no previous URLs.
300300
/// - topicImages: Images that are used to represent the summarized element, or `nil` if this element has no topic images.
301301
/// - 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 {
483483
let abstract = renderSymbolAbstract(symbol.abstractVariants[summaryTrait] ?? symbol.abstract)
484484
let usr = symbol.externalIDVariants[summaryTrait] ?? symbol.externalID
485485
let fullName = symbol.fullName(for: summaryTrait)
486-
let declaration = (symbol.declarationVariants[summaryTrait] ?? symbol.declaration).renderDeclarationTokens()
487486
let language = documentationNode.sourceLanguage
488-
487+
// Use the abbreviated declaration fragments instead of the full declaration fragments.
488+
// These have been derived from the symbol's subheading declaration fragments as part of rendering.
489+
// We only want an abbreviated version of the declaration in the link summary (for display in Topic sections, the navigator, etc.).
490+
// Otherwise, the declaration would be too verbose.
491+
//
492+
// However if no abbreviated declaration fragments are available, use the full declaration fragments instead.
493+
// In this case, they are assumed to be the same.
494+
let declaration = renderNode.metadata.fragmentsVariants.value(for: language) ?? (symbol.declarationVariants[summaryTrait] ?? symbol.declaration).renderDeclarationTokens()
495+
489496
let variants: [Variant] = documentationNode.availableVariantTraits.compactMap { trait in
490497
// Skip the variant for the summarized elements source language.
491498
guard let interfaceLanguage = trait.interfaceLanguage, interfaceLanguage != documentationNode.sourceLanguage.id else {
492499
return nil
493500
}
494501

495-
let declarationVariant = symbol.declarationVariants[trait]?.renderDeclarationTokens()
496-
497502
let abstractVariant: Variant.VariantValue<Abstract?> = symbol.abstractVariants[trait].map { renderSymbolAbstract($0) }
498503

499504
func nilIfEqual<Value: Equatable>(main: Value, variant: Value?) -> Value? {
@@ -502,6 +507,15 @@ extension LinkDestinationSummary {
502507

503508
let fullNameVariant = symbol.fullName(for: trait)
504509
let variantTraits = [RenderNode.Variant.Trait.interfaceLanguage(interfaceLanguage)]
510+
511+
// Use the abbreviated declaration fragments instead of the full declaration fragments.
512+
// These have been derived from the symbol's subheading declaration fragments as part of rendering.
513+
// We only want an abbreviated version of the declaration in the link summary (for display in Topic sections, the navigator, etc.).
514+
// Otherwise, the declaration would be too verbose.
515+
//
516+
// However if no abbreviated declaration fragments are available, use the full declaration fragments instead.
517+
// In this case, they are assumed to be the same.
518+
let declarationVariant = renderNode.metadata.fragmentsVariants.value(for: variantTraits) ?? symbol.declarationVariants[trait]?.renderDeclarationTokens()
505519
return Variant(
506520
traits: variantTraits,
507521
kind: nilIfEqual(main: kind, variant: symbol.kindVariants[trait].map { DocumentationNode.kind(forKind: $0.identifier) }),

‎Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift‎

Lines changed: 2 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -296,8 +296,6 @@ class LinkDestinationSummaryTests: XCTestCase {
296296
.init(text: " ", kind: .text, identifier: nil),
297297
.init(text: "globalFunction", kind: .identifier, identifier: nil),
298298
.init(text: "(", kind: .text, identifier: nil),
299-
.init(text: "_", kind: .identifier, identifier: nil),
300-
.init(text: ": ", kind: .text, identifier: nil),
301299
.init(text: "Data", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "s:10Foundation4DataV"),
302300
.init(text: ", ", kind: .text, identifier: nil),
303301
.init(text: "considering", kind: .identifier, identifier: nil),
@@ -530,10 +528,6 @@ class LinkDestinationSummaryTests: XCTestCase {
530528
.init(text: " ", kind: .text, identifier: nil),
531529
.init(text: "myStringFunction", kind: .identifier, identifier: nil),
532530
.init(text: "(", kind: .text, identifier: nil),
533-
.init(text: "_", kind: .externalParam, identifier: nil),
534-
.init(text: " ", kind: .text, identifier: nil),
535-
.init(text: "string", kind: .internalParam, identifier: nil),
536-
.init(text: ": ", kind: .text, identifier: nil),
537531
.init(text: "String", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "s:SS"),
538532
.init(text: ") ", kind: .text, identifier: nil),
539533
.init(text: "throws", kind: .keyword, identifier: nil),
@@ -551,17 +545,8 @@ class LinkDestinationSummaryTests: XCTestCase {
551545
XCTAssertEqual(variant.title, "myStringFunction:error:")
552546
XCTAssertEqual(variant.fullName, "+ (NSString *) myStringFunction: (NSString *)string error: (NSError **)error;")
553547
XCTAssertEqual(variant.declarationFragments, [
554-
.init(text: "+ (", kind: .text, identifier: nil),
555-
.init(text: "NSString", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "c:objc(cs)NSString"),
556-
.init(text: " *) ", kind: .text, identifier: nil),
557-
.init(text: "myStringFunction", kind: .identifier, identifier: nil),
558-
.init(text: ": (", kind: .text, identifier: nil),
559-
.init(text: "NSString", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "c:objc(cs)NSString"),
560-
.init(text: " *)string ", kind: .text, identifier: nil),
561-
.init(text: "error", kind: .identifier, identifier: nil),
562-
.init(text: ": (", kind: .text, identifier: nil),
563-
.init(text: "NSError", kind: .typeIdentifier, identifier: nil, preciseIdentifier: "c:objc(cs)NSError"),
564-
.init(text: " **)error;", kind: .text, identifier: nil)
548+
.init(text: "+ ", kind: .text, identifier: nil),
549+
.init(text: "myStringFunction:error:", kind: .identifier, identifier: nil)
565550
])
566551

567552
// Check variant content that is the same as the summarized element

‎Tests/SwiftDocCTests/Model/SemaToRenderNodeMultiLanguageTests.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -556,7 +556,7 @@ class SemaToRenderNodeMixedLanguageTests: XCTestCase {
556556
"myStringFunction:error:",
557557
],
558558
referenceFragments: [
559-
"typedef enum Foo : NSString {\n ...\n} Foo;",
559+
"+ myStringFunction:error:",
560560
],
561561
failureMessage: { fieldName in
562562
"Objective-C variant of 'MyArticle' article has unexpected content for '\(fieldName)'."

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

Lines changed: 8 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -366,46 +366,13 @@
366366
}
367367
],
368368
"subHeading" : [
369-
{
370-
"kind" : "keyword",
371-
"spelling" : "typedef"
372-
},
373369
{
374370
"kind" : "text",
375-
"spelling" : " "
376-
},
377-
{
378-
"kind" : "keyword",
379-
"spelling" : "enum"
380-
},
381-
{
382-
"kind" : "text",
383-
"spelling" : " "
371+
"spelling" : "+ "
384372
},
385373
{
386374
"kind" : "identifier",
387-
"spelling" : "Foo"
388-
},
389-
{
390-
"kind" : "text",
391-
"spelling" : " : "
392-
},
393-
{
394-
"kind" : "typeIdentifier",
395-
"spelling" : "NSString",
396-
"preciseIdentifier": "c:@T@NSInteger"
397-
},
398-
{
399-
"kind": "text",
400-
"spelling": " {\n ...\n} "
401-
},
402-
{
403-
"kind": "identifier",
404-
"spelling": "Foo"
405-
},
406-
{
407-
"kind": "text",
408-
"spelling": ";"
375+
"spelling" : "myStringFunction:error:"
409376
}
410377
]
411378
},
@@ -485,7 +452,7 @@
485452
"text" : "This is the foo's description."
486453
}
487454
]
488-
},
455+
}
489456
},
490457
{
491458
"accessLevel" : "public",
@@ -570,7 +537,7 @@
570537
{
571538
"kind" : "typeIdentifier",
572539
"spelling" : "NSString",
573-
"preciseIdentifier": "c:@T@NSInteger",
540+
"preciseIdentifier": "c:@T@NSInteger"
574541
},
575542
{
576543
"kind": "text",
@@ -630,7 +597,7 @@
630597
"kind" : "identifier",
631598
"spelling" : "first"
632599
}
633-
],
600+
]
634601
},
635602
"pathComponents" : [
636603
"Foo",
@@ -677,7 +644,7 @@
677644
"kind" : "identifier",
678645
"spelling" : "fourth"
679646
}
680-
],
647+
]
681648
},
682649
"pathComponents" : [
683650
"Foo",
@@ -724,7 +691,7 @@
724691
"kind" : "identifier",
725692
"spelling" : "second"
726693
}
727-
],
694+
]
728695
},
729696
"pathComponents" : [
730697
"Foo",
@@ -771,7 +738,7 @@
771738
"kind" : "identifier",
772739
"spelling" : "third"
773740
}
774-
],
741+
]
775742
},
776743
"pathComponents" : [
777744
"Foo",

0 commit comments

Comments
 (0)