ExternalDocumentationSource

A type that resolves references to documentation from other sources.

protocol ExternalDocumentationSource

Mentioned In

Linking Between Documentation

Discussion

Use this protocol to integrate documentation content from other sources. Your implementation needs to be able to:

Resolve references for the bundle identifier for which it’s registered.
Create entities for the references it was able to resolve.

When the documentation context encounters a reference that can’t be resolved locally, it checks whether an external documentation source is registered in externalDocumentationSources for the bundle identifier of the unresolved reference. If there is, that source is asked to attempt to resolve the reference.

If the referenced documentation exists in the external source, the source returns a resolved reference to the context. Later, the context uses this resolved reference to ask the source for the external entity with the documentation content for that reference. Because this content isn’t part of the compiled bundle, it won’t have its own page in the build output.

If the reference doesn’t exist in the external source of documentation or if an error occurs while attempting to resolve the reference, the external source returns information about the error.

Topics

Instance Methods

func resolve(TopicReference) -> TopicReferenceResolutionResult
Attempts to resolve an unresolved reference for an external topic.