Formally deprecate additionalSymbolGraphFiles property

[d-ronnqvist]

Bug/issue #, if applicable:

Summary

This formally deprecates Convert.additionalSymbolGraphFiles. It has long been replaced by additionalSymbolGraphDirectory.

Dependencies

None

Testing

• Run docc convert Empty.docc --additional-symbol-graph-files /path/to/Something.symbols.json

  • There should be a warning on the CLI (this was already there before)

    warning: '--additional-symbol-graph-files' is deprecated. Use '--additional-symbol-graph-dir' instead.

• In SwiftDocCUtilities, access Convert.additionalSymbolGraphFiles

  • There should be a warning that it's deprecated API that will be removed in the future.

Checklist

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

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

[patshaughnessy]

LGTM

[patshaughnessy]

Is this a common Swift idiom?

[d-ronnqvist]

Not really. Normally there's no need to cast a value to one of the protocols that it's known to conform to but here I'm leveraging the downcast to shadow the deprecated API with a non-deprecated API to avoid a deprecation warning. This comment explains how it works in more detail.

[patshaughnessy]

And, how does this actually work? By extending Docc.Convert so it conforms to a private protocol, are we preventing any other code from using the attributes (additionalSymbolGraphFiles) of this private protocol outside of this file?

[daniel-grumberg]

IIUC the aim here is to force DocC.Convert to expose the additionalSymbolGraphFiles property, for this code here to work (I assume that David audited the code for further uses of additionalSymbolGraphFiles), Once 5.11 is released then we will go back and remove the property entirely which will cause this code to fail to compile and therefore force us to go remove this use of it. This only works if we don't introduce new uses of the property, but I don't see why we would.

[d-ronnqvist]

Docc.Convert already has an additionalSymbolGraphFiles property but it's marked as deprecated here. Since it's deprecated, any code that accesses it will result in a deprecation warning, even within the same module.

That leaves us with 3 choices:

• Do nothing and live with the added depreciation warnings for a couple of releases.
• Stop accessing the deprecated API property, breaking the behavior for any client who passes this flag
• Write a bit of extra code to be able to avoid the deprecation warning.

I opted for the third choice. The way this private protocol avoids the deprecation warning works in 3 steps:

•  private protocol _DeprecatedSymbolGraphFilesAccess {
       var additionalSymbolGraphFiles: [URL] { get }
   }

  defines a protocol with a property with the same name and type as the deprecated API. This property of this protocol isn't deprecated. This protocol is only available within this source file.

•  extension Docc.Convert: _DeprecatedSymbolGraphFilesAccess {}

  conforms the Convert command to this private protocol. Since Convert already has a property with this name and type it doesn't need to implement anything new.

•  (convert as _DeprecatedSymbolGraphFilesAccess).additionalSymbolGraphFiles

  casts the convert value to the deprecated property; thus shadowing the deprecated Convert.additionalSymbolGraphFiles with the not deprecated _DeprecatedSymbolGraphFilesAccess.additionalSymbolGraphFiles

It looks rather strange but it allows us to internally call the deprecated API without warnings about it being deprecated. I know that there aren't other places who access Convert.additionalSymbolGraphFiles because those would result in deprecation warnings. If any new code called Convert.additionalSymbolGraphFiles it would work but result in a deprecation warning.

[d-ronnqvist]

@swift-ci please test