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.

[grynspan]

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