Move configuration before context initialization

[d-ronnqvist]

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

Summary

This is the first of many changes to redefine how documentation contexts are created. This change specifically moves configuration that's intended to be immutable before the context is initialized.

For source compatibility changes we can't make that configuration actually immutable, but we can warn about any code that modifies after the context is created (and after 6.2 we can make them actually immutable).

Future PRs will build on top of this to change how documentation bundles are discovered and provided to DocC. The ultimate goal is to simplify and decouple the documentation build process so that it can be separated into reusable pieces that other commands can use for build-related and rendering-related work.

Dependencies

None

Testing

Nothing in particular. This is

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

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

The changes in this file are probably the best illustration of what this PR is about.

Before the code looked like

// 1: Create context
    let context = DocumentationContext(dataProvider: workspace, ...)

// 2: Make configuration

    context.externalMetadata.inheritDocs = inheritDocs
    context.externalMetadata.diagnosticLevel = filterLevel

    if let outOfProcessResolver {
        context.externalDocumentationSources[outOfProcessResolver.bundleIdentifier] = outOfProcessResolver
        context.globalExternalSymbolResolver = outOfProcessResolver
    }

    // Later, in another method of another type that the context is passed to ...

// 3: "Register" the data provider
    try workspace.registerProvider(dataProvider, ...)

but now it looks like

Before the code looked like

// 1: Make configuration
    var configuration = DocumentationContext.Configuration()

    configuration.externalMetadata.inheritDocs = inheritDocs
    configuration.externalMetadata.diagnosticLevel = filterLevel

    if let outOfProcessResolver {
        configuration.externalDocumentationConfiguration.sources[outOfProcessResolver.bundleIdentifier] = outOfProcessResolver
        configuration.externalDocumentationConfiguration.globalSymbolResolver = outOfProcessResolver
    }

// 2: Create context
    let context = DocumentationContext(dataProvider: workspace, ..., configuration: configuration)

    // Later, in another method of another type that the context is passed to ...
    
// 3: "Register" the data provider
    try workspace.registerProvider(dataProvider, ...)

The impact of this is that the window where it's possible to set these values is narrowed to a handful of lines in a single function (from the creation of the "configuration" to the creation of the "context").

Previously, one could continue changing these values all the way until the try workspace.registerProvider(dataProvider, ...) call and it was possible to change them after that as well, although that wouldn't have worked correctly because the values would have already been read when registering the data provider.

[d-ronnqvist]

This silences a deprecation warning. We can't get rid of this line without causing breaking changes in case someone passed a context to the ConvertAction initializer (the default value for that parameter is nil).

[d-ronnqvist]

This test is an example of the bug that was possible with the previous code. These "expected" values are actually the unresolved external links.

The bug in this test is that the configuration (the external documentation source) is added after registering the data provider with the workspace and context.

try workspace.registerProvider(dataProvider)
let context = try DocumentationContext(dataProvider: workspace)

// At this point the context has already "built" all documentation
//
// Any changes after this point has no effect. 
// Specifically, any external links have already failed to resolve and the context won't try again.

context.externalDocumentationSources = ["com.external.testbundle" : ExternalReferenceResolverTests.TestExternalReferenceResolver()]

[d-ronnqvist]

This is another example of a test that with the bug of making configuration changes after the context has "registered" the documentation, thus having no effect and verifying that the links aren't resolved.

[d-ronnqvist]

This didSet isn't needed because the setter is private and no code path needs to reconfigure the new context.

[d-ronnqvist]

This loop comes from here.

In the old code it looked like setting the current platforms here did something but that value was actually written over by the DocumentationConverter that the ConvertAction creates at the end of this initializer (and passes a shared reference to the context to).

[d-ronnqvist]

@swift-ci please test