Begin including SPI documentation in local builds, and fix all newly-revealed DocC issues

[stmontgomery]

Begin including documentation for @_spi declarations in local development (non-distribution) builds, and fix all newly-revealed DocC issues in those SPI declarations.

I also took this opportunity to simplify the mechanism for conditionalizing certain package settings for distribution builds, and fix a few other documentation omissions and inconsistencies I noticed.

Checklist:

• Code and documentation should follow the style of the Style Guide.
• If public symbols are renamed or modified, DocC references should be updated.

Resolves rdar://118416838

[stmontgomery]

@swift-ci please test

[stmontgomery]

Even though I still like the idea of this setting, in practice it is not giving us any benefit or protection since currently it must be commented-out for distribution builds (which are the usage scenario it was meant for). Having it here causes us an additional manual step each time we cut a release, and there's little practical value in conditionalizing it to only non-distribution builds IMO.

[stmontgomery]

I confirmed that the rendered DocC still shows the documentation block comments above, despite having 2-slash // comments in between.

[grynspan]

Please hold on to this PR.

[grynspan]

What if instead we checked for an environment variable and built SPI when it's set?

let buildSPIDocumentation: Bool = {
  if let boolValue = Context.environment["SWT_SPI_DOCUMENTATION_ENABLED"].flatMap(Bool.init) {
    return boolValue
  } else if let intValue = Context.environment["SWT_SPI_DOCUMENTATION_ENABLED"].flatMap(UInt64.init) {
    return intValue != 0
  }
  return false // disabled by default
}()

(That's a slightly simplified version of what our own Environment type does.)

[stmontgomery]

We could do this, although a workflow I commonly use for viewing docs is the "Product > Build Documentation" command in recent versions of Xcode, and I was hoping for that to get this flag too. I don't know of a way to apply an env var in that scenario (when using the GUI Xcode app, not its xcodebuild CLI).

[stmontgomery]

The constant I added here would still be needed, or at least it would still be helpful, even if we conditionalized the SPI docs flag based on an env var, because the constant is what (now) decides whether all the unsafeFlags get included

[grynspan]

Honestly we can also just drop the unsafe flags outright.

[grynspan]

although a workflow I commonly use for viewing docs is the "Product > Build Documentation" command in recent versions of Xcode

We can ask the DocC folks if they can help with this.

[Kyle-Ye]

We could do this, although a workflow I commonly use for viewing docs is the "Product > Build Documentation" command in recent versions of Xcode, and I was hoping for that to get this flag too. I don't know of a way to apply an env var in that scenario (when using the GUI Xcode app, not its xcodebuild CLI).

+1 for some similar scenario I experienced. And I believe it is a Xcode/SwiftPM issue instead of a DocC issue.

Xcode GUI only gives us the ability to set env value for executable target when they are running. I could not find a easy solution to setup the env value I use in my Package.swift file.

Currently I just use a small macOS app I wrote to trigger export XX=YY && open ./ -a Xocde for me in Finder.

Otherwise we'll have to quit Xcode and manually export the env value in shell and then open Xcode in the shell to make Package.swift access the env we set.

As a person who maintains some Swift packages and likes to add environment variable condition config in package, it is really troublesome at present if we do not use any other 3rd party tools.

[grynspan]

I think we can avoid having to manually toggle isBuildingForDistribution. See my comment above about an environment variable.