something i noticed while browsing through SwiftNIO docs as rendered by
swift-biome: the library references documentation for underscored symbols like
_EmittingChannelHandler, etc., but these symbols are invisible to
swift-biome and other SymbolGraphGen-based tools, including DocC.
this means that Jazzy (the SourceKit-based backend version) is the only documentation compiler that currently works for SwiftNIO.
i’m not sure how complicated it would be to move the library off of these underscored APIs. but having passages like:
Please refer to
_EmittingChannelHandler for more details on the provided methods.
when these pages do not actually exist does not seem great…
How much of this is a SwiftNIO issue rather than DocC/SymbolGraph?
Those types are publicly defined, but they're not exported because of the special nature of
_ in symbol names.
this is a matter of opinion. personally i think SymbolGraphGen would be better off emitting all the symbols by default (regardless of implicitly private access), but others feel strongly that underscored APIs are not public APIs and therefore should not be picked up by documentation compilers.
this is not a DocC issue, as DocC is a consumer of SymbolGraphGen, just like
related discussion: (SymbolGraphGen) can we make `isImplicitlyPrivate` checking configurable?
This is untenable. The better option is to move the documentation off those APIs. Can you file a Github issue to track that please?
how would you move the documentation off those APIs? the requirements themselves are being stripped from the symbol graph, so there would be no symbols to attach said documentation to…
Oh interesting, I hadn't realised that the doc did not render the protocol requirements in the case where it has erased the upstream protocol. That seems less than ideal: I think that we do need to find a way to cut through the limitations of SymbolGraphGen here.
I don't think emitting underscored symbols in symbol graph files makes sense by default, but emitting the (non-underscored) synthesised symbols that originate from underscored protocols makes sense to me (like the SwiftNIO case discussed above). I'd be interested in seeing how many additional symbols we produce for the standard library and do an audit of the results.
just a nit, but the
_ChannelInboundHandler methods aren’t synthesized symbols, they would only appear for concrete types that conform to
ChannelInboundHandler. the problem here is
ChannelInboundHandler implies a conformance to
_ChannelInboundHandler, but DocC/Biome knows nothing about
_ChannelInboundHandler, so it display its requirements.
there is yet another blocker now, as members originating from underscored protocols are no longer being inherited at all: GitHub issue
update: this has been partially unblocked by @QuietMisdreavus ’s PR. thanks victoria!
To follow up: i've filed apple/swift#60163 to track adding a flag when generating symbol graphs to include underscored and "unconditionally unavailable" symbols.