Don't document anything SPI-public

[mludowise-stripe]

We recently started Swift's new SPI (System Programming Interfaces) support to expose classes & methods to other modules within our ecosystem. To use this, we annotate our SPI-available classes with @_spi(STP) public class MyClass {...} (where STP is our own namespace). Here's an example in our repo.

Our intent is that no one should use anything SPI-exposed with the STP namespace in our API except for the modules that we own. So we don't want anything that is exposed using @_spi(STP) to be displayed in our docs.

Currently, we're able to avoid most of SPI-conforming classes, types, and methods from getting exposed in our docs by using the :nodoc:, however any public class that conforms to an SPI-public protocol still displays its protocol conformance like this:

Steps to reproduce:

1. git clone [email protected]:stripe/stripe-ios.git && cd stripe-ios && checkout origin/mludowise/spi_jazzy_example
2. ./ci_scripts/build_documentation.sh
   • This invokes jazzy --podspec Stripe.podspec but does some extra stuff to setup a temporary podspec repo as a workaround for Cannot build docs from podspec with unpublished dependency pod #1262
   • I've also already built the docs on this branch, so you can view the result directly in the docs directory
3. open docs/docs/Classes/STPApplePayContext.html

This is the git branch containing my example: https://github.com/stripe/stripe-ios/tree/mludowise/spi_jazzy_example

Proposal

Omit anything annotated with @_spi(...) from generated docs by default.

You could add an optional flag like --include-swift-spi namespace,namespace,... if the documenter wants the ability to explicitly include SPI documentation for specific namespaces. Although, typically the purpose of a System Programming Interfaces is for internal uses, so I'm doubtful that it's necessary or useful to include a flag like this.

I think the solution would involve skipping documentation for anything that has @_spi in the key.parsed_declaration entry from sourcekitten, but I'm not completely sure about that.

[johnfairh]

We should do this -- I was hoping that @_spi would be made non-underscored this year and get some proper tooling support to make the implementation easier but will have to do without.

I think it's safer to include the flag, users find all kinds of ways of using jazzy including internal documentation and not including a way to say 'include all public APIs including SPI' feels like pushing work down the line (eg. docs for someone who has to consume the SPI in question).

---

In the case you mention above of not wanting to see the STPAnalyticsProtocol conformance, you should be able to :nodoc: the extension that adds it, something like

/// :nodoc:
@_spi(foo) extension C : P {
...
}

It's probably a bug in :nodoc: if this doesn't work.

[mludowise-stripe]

Good point about making it an option to include SPI documentation. I feel like there could be some wonky edge cases with trying to explicitly include some SPI name spaces but not others...

For example, what is the expected behavior if you pass --include-swift-spi FOO for the following:

@_spi(FOO) @_spi(BAR) public class MyClass {...}

Perhaps making it a simple boolean flag where either all or no SPI-public APIs are included in documentation would suffice.

---

Thanks for noting we should be able to use :nodoc:. I swear I tried this before and I couldn't get working, but I must have been doing something wrong because now it seems to be working 🤪. Thank you!

[johnfairh]

I've taken a closer look at @_spi and made a first attempt at Jazzy support.

I agree with you that getting into the details of SPI groups is way too much right now: the implementation is pretty shaky and I'd expect it to change on the way to becoming a real Swift feature. And the main Jazzy feature is as originally requested, to just exclude them: so we'll go with a single flag to opt back in any @_spi.

[johnfairh]

Fixed in master.