Question for the folks who've tackled organizing documentation with Docc previously (@BoisyPitre ?): How do you add organization to a symbol to cover the cases where the compiler synthesized a whole pile of code for you?
The code I'm working on has a number of protocol conformances, and the rendered documentation generates this sort of crazy cluster of groupings for all the various methods that the compiler synthesized. As an example:
(The duplicate that's just named "Implementations" in the screenshot has been reported as a bug: [SR-15556] Duplicate conformance sections generated from synthesized conformance in Docc · Issue #201 · apple/swift-docc · GitHub))
When I tried to add markdown H3 tags to the documentation details for the relevant struct, the code completion in Xcode didn't recognize any of these symbols. I recognize this might be an issue in Xcode's code completion for Docc symbols.
I did try just stubbing in the symbols and hoping they'd override:
/// ### Comparing MyStruct
///
/// - ``MyStruct/<(_:_:)``
/// - ``MyStruct/>(_:_:)``
/// - ``MyStruct/>=(_:_:)``
/// - ``MyStruct/<=(_:_:)``
But it didn't render through at all (content was ignored in the output, and not even "Comparing MyStruct" was visible in the result - and each of the attempted links returned an error in Xcode: Link destination '...' is not a valid URL
.
Is there a workaround to make these sets of methods at least organized a bit more nicely, or am I stuck with what docc provides in these cases today?