Set DOCC_EXTRACT_EXTENSION_SYMBOLS=NO in doc builds

[finestructure]

There's a regression when generating docs with 5.9 (at least for iOS, not sure if it affects SPM as well).

@QuietMisdreavus suggests to set DOCC_EXTRACT_EXTENSION_SYMBOLS=NO by default.

See GetStream/stream-chat-swiftui#369 (comment) for details.

Victoria, I presume this would also affect swift package generate-documentation builds and not just xcodebuild docbuild?

If so, does this also look for the env variable or is there some other mechanism? I'm asking because I vaguely recall the two are configured differently in some regards.

[QuietMisdreavus]

It may not affect swift package generate-documentation, but i'm not confident - it was a default behavior that changed between Xcodes 14.3 and 15. I'm not sure if the plugin adds extension symbols to documentation output, or how that would be controlled. /cc @ethan-kusters

[stevapple]

Since this is a feature enabled in Swift 5.9 (Xcode and SPM plugin) by default, maybe we should find out a better way. Personally I’m expecting this to be the default.

I'm not sure if the plugin adds extension symbols to documentation output, or how that would be controlled.

IIRC it’s changed from an opt-in feature to a default one for Swift 5.9+. See swiftlang/swift-docc-plugin#57.

[ethan-kusters]

I think I would hold off on setting this globally until we have more evidence that this is widespread issue. If it is widespread, then we should really change the default in the swift-docc-plugin itself instead of in (or in addition to) SPI.

If there are specific packages where this causes breakage, I would file tracking issues on Swift-DocC and disable the feature for that particular package using the .spi.yml.

[finestructure]

Is the error message

SwiftDocC/DocumentationContext.swift:1206: Fatal error: Symbol with identifier 's:10StreamChat19MessageReactionTypeV0aB7SwiftUIE2idSSvp' has no reference. A symbol will always have at least one reference.
Command CompileDocumentation failed with a nonzero exit code

in the original report unique to this failure? If so we should be be able to see if this is happening in other cases. A bit fiddly but possible.

[d-ronnqvist]

I believe that this crash is solved by swiftlang/swift-docc#720 which should be a fairly uncommon setup with a local symbol shadowing the name of an extended module.

[d-ronnqvist]

Is the error message

SwiftDocC/DocumentationContext.swift:1206: Fatal error: Symbol with identifier 's:10StreamChat19MessageReactionTypeV0aB7SwiftUIE2idSSvp' has no reference. A symbol will always have at least one reference.
Command CompileDocumentation failed with a nonzero exit code

in the original report unique to this failure? If so we should be be able to see if this is happening in other cases. A bit fiddly but possible.

In practice I think we can rely on the "A symbol will always have at least one reference." precondition being unique to this failure.

[finestructure]

Thanks for the additional details, @d-ronnqvist! It sounds like the issue should be pretty rare. It's not super-straightforward to check the logs for this error, so I'll hold off doing this for now unless you all are really concerned about this being a bigger issue - maybe something to discuss next Monday.

[finestructure]

I'll close this for now. We discussed this and concluded it's very likely a rare edge case.