Populate abbreviated declaration fragments in external render nodes

[anferbui]

Bug/issue #, if applicable: rdar://156488052

Summary

Improves the quality of the navigator titles for external render nodes. Navigator titles are derived from the item's declaration fragments when at least one of the following is met 1:

• the source language is Swift
• there is no available navigator title
• the page type is not part of a curated list 2

These declaration fragments are expected to be the abbreviated declaration fragments 3 of the symbol.

This PR helps capture the abbreviated declaration fragments of the symbol for external entities, so that they can be used in the navigator. The final goal is to have external entities in the navigator render no differently from local entities.

Implementation

There was no change needed to the LinkResolver.ExternalEntity type, as some declaration fragments were already being stored as part of LinkResolver.ExternalEntity.TopicRenderReference.fragmentsVariants 4.

The main issue was that while OutOfProcessReferenceResolver.ResolvedInformation relied on the fragments that it was receiving from the OutOfProcessReferenceResolver to be the abbreviated declaration fragments, LinkDestinationSummary was only encoding the full declaration fragments only as part of its summary:

swift-docc/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift

Line 445 in 1b4a185

let declaration = (symbol.declarationVariants[summaryTrait] ?? symbol.declaration).renderDeclarationTokens()

swift-docc/Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift

Line 454 in 1b4a185

let declarationVariant = symbol.declarationVariants[trait]?.renderDeclarationTokens()

The abbreviated declaration fragments are different from the full declaration fragments and defined as a different field (subHeading 5) in the symbol graph (and therefore cannot be derived by DocC), but they're ultimately processed and captured as part of RenderMetadata.fragmentsVariants 6.

The main changes needed were to update the documentation of OutOfProcessReferenceResolver.ResolvedInformation and LinkDestinationSummary to have an extra property, subHeadingDeclarationFragments, which stores the abbreviated declaration fragments. These declaration fragments can then be used when initialising LinkResolver.ExternalEntity.TopicRenderReference.fragmentsVariants.

More detail on the implementation can be found in commit 832f1eb.

Alternatives considered

Considered modifying LinkDestinationSummary.declarationFragments instead of adding a new optional field, however the full declaration fragments are used to determine the full name 7 of the symbol for diagnostic reporting 8.

By introducing a new field we also ensure this is a non-breaking change.

Navigator comparison (using swift-docc-render):

This compares what it looks like to refer to those symbols within its local DocC bundle versus what it would look like to curate them as external links:

Local	External

And if we also bring in the symbol kind changes from #1251, it becomes even closer:

Local	External

Dependencies

N/A

Testing

Verified by using 2 bundles -- one for generating linkable entities, another for referencing an external link from the other bundle -- and verifying that the declaration fragments in the linkable entities are the abbreviated, subheading declaration fragments.

Steps:

1. Download and extract the test bundles: Example.zip
2. Build the linkable entities for the first bundle: swift run docc preview ExampleA.docc --emit-digest
   a. Look at http://localhost:8000/documentation/mykit
   b. Look at the Topics section and the navigator titles for both the class and the function
3. Modify the link resolver in the second bundle to resolves the updated linkable entities for the first bundle
4. Build the linkable entities for the second bundle: DOCC_LINK_RESOLVER_EXECUTABLE=ExampleB.docc/bin/test-data-external-resolver swift run docc preview ExampleB.docc
5. Verify that the Topics section and the navigator titles match the ones from step 2b.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added Updated tests
• Ran the ./bin/test script and it succeeded
• Updated documentation if necessary

[anferbui]

Some tests are failing in ExternalPathHierarchyResolverTests which look like the error diagnostics were requiring the full declaration fragments for external links. Needs investigation.

The full declaration fragments are used to determine the full name of the symbol for diagnostic reporting:

swift-docc/Sources/SwiftDocC/Infrastructure/Link Resolution/PathHierarchy+Error.swift

Lines 115 to 117 in 1b4a185

	return Solution(summary: "\(Self.replacementOperationDescription(from: foundDisambiguation, to: suggestedDisambiguation, forCollision: true)) for \n\(fullName.singleQuoted)", replacements: [
	Replacement(range: replacementRange, replacement: suggestedDisambiguation)
	])

I think we will need a new field in LinkDestinationSummary to contain the abbreviated declaration fragments rather than re-using the existing one.

[anferbui]

I've updated the implementation so that all unit tests should now pass.

[anferbui]

@swift-ci please test

[anferbui]

@swift-ci please test

[sofiaromorales]

Thanks for the incredible work on documenting this PR, Andrea!

The only question I have about the implementation is if TopicRenderReference only takes fragments, and not subheadingFragments [1], why do we need to add subHeadingDeclarationFragments into the ResolvedInformation [2]? Can't we simply keep the summarized version and default its value to the full declaration from the LinkDestinationSummary in case this is nil?

[1] https://github.com/swiftlang/swift-docc/pull/1255/files#diff-c195a5776f681e560e52fc959b22479573bbc847217e4ba4b66c0a0f29f31424L169
[2] https://github.com/swiftlang/swift-docc/pull/1255/files#diff-c195a5776f681e560e52fc959b22479573bbc847217e4ba4b66c0a0f29f31424R584

[sofiaromorales]

Is there an example where the subheading declaration fragments and the full declaration fragments are not the same?

[sofiaromorales]

If the subheading declaration fragments it's used instead of the fragments in the TopicRenderReference why do we want to keep declarationFragments here instead of only keeping the subheading one?