Register references resolved by fallback resolvers

[franklinsch]

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

Summary

Resolves an issue when using ConvertService where link resolution fails in doc comments of top-level symbols. For example, in:

/// Link to ``bar()``.
public struct Foo {
  public func bar() {}
}

The link to bar() does not resolve.

The issue started appearing with #74, where DocC started (correctly) percent-encoding : characters in symbol links. The reason is that when ReferenceResolver resolves symbol links, it rewrites them with their full absolute link: ``Foo/bar()`` becomes ``doc://org.swift.example/documentation/Foo/bar()``.

When resolving the link again (in RenderNodeTranslator) during a compilation build (not ConvertService), the URL of the symbol link is looked up in DocumentationContext.referencesIndex, which contains an absolute URL -> resolved reference mapping. This mapping is populated during bundle registration.

However, when using ConvertService, externally-resolved references that are members of the bundle being compiled were not getting added to the referencesIndex mapping. This meant that the reference was getting resolved externally again rather than being looked up in the index.

Then, with #74, ``doc://org.swift.example/documentation/Foo/bar() `` (correctly) became a URL with path doc://org.swift.example/documentation/Foo/bar() rather than a URL with path /documentation/Foo/bar(). Hence, the resolution request being made was for doc://org.swift.example + the path, i.e., doc://org.swift.example/doc://org.swift.example/documentation/Foo/bar(), which is invalid. This was never an issue for regular docc-based compilations, because the reference was looked up in DocumentationContext.referencesIndex and never re-resolved.

This PR aligns the ConvertService and docc-based compilations by registering references resolved by fallback resolvers in the documentation context, so that they can be looked up for subsequent resolutions.

Dependencies

None.

Testing

Build documentation for the Swift example shown above using ConvertService and verify that the link resolves.

Checklist

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

[franklinsch]

@swift-ci please test

[franklinsch]

@swift-ci please test

[d-ronnqvist]

This looks good to me.

As a follow up it would be nice to rename registerReference(_:) and referenceIndex to be more specific. These have broad sounding names but are used for a more narrow purpose (only for local symbol references from what I could tell).

[jackhl]

I'm not entirely following what's happening here, but this is concerning:

when ReferenceResolver resolves symbol links, it rewrites them with their full absolute link: Foo/bar() becomes doc://org.swift.example/documentation/Foo/bar().

Using a fully-qualified url including the scheme is invalid within double-backtick symbol links; only paths should be allowed there.

[jackhl]

The issue started appearing with #74, where DocC started (correctly) percent-encoding : characters in symbol links.

I don't see where percent-encoding is happening that PR. In any case, why is it correct to percent-encode symbol links?

[franklinsch]

Yes, having a full URL with a host is odd to have in a symbol link. DocC is correctly percent-encoding the symbol link destination so that's it's a valid URL path. This stems from ReferenceResolver rewriting the SymbolLink markup to include the fully-qualified resolved URL, but it should be writing as a plain Link instead. This is an improvement that we should do in a follow-up PR, but this PR just aligns the ConvertService and docc-based compilations for now. I've been trying to file a bug for this on bugs.swift.org but it seems like there are ongoing issues with JIRA at the moment.

[franklinsch]

@swift-ci please test