Hi.
Last year, I wrote a feature request for docc (here). A month ago it was moved from the docc-Repository into the swift-repository.
I still think that it is a request for a docc-feature not a compiler feature. Maybe it is a compiler feature but my request if it was moved on purpose is still unanswered.
Could anyone explain to me why it was moved?
I suspect the logic for attaching documentation comments to a particular Swift symbol lives outside of the swift-docc repo, possibly in the main swift repo. I doubt Ethan would move it on accident; he works on DocC and would know what's in the scope of the repo. Perhaps he forgot to add a rationale comment when moving it over.
@dhoepfl I'm fairly sure it's because of the flow of how DocC does its work. There's a whole bunch of preliminary stuff that's the output from the compiler itself - what's called "symbol generation". That's the process that seeds information about a specific symbol flows from your source file to DocC. The issue you posted was all about collecting the documentation for different locations relative to the symbol, which is a change to how symbol generation works so it can grab that detail from other areas.
So the bits that need to be updated/changed to address what your issue are all within the Swift compiler, and more specifically within the symbol-graph generation section of it.
Thanks @krilnon and @Joseph_Heck for jumping in here!
I'll update the GitHub Issue as well – but this is exactly right. Swift-DocC is designed to be programming-language agnostic. It doesn't know how to parse documentation comments out of Swift source code, it relies on the Swift compiler to do this and just receives data from the compiler (in the form of symbol graph files) that contains the extracted documentation comments. (Swift-DocC's integration with Objective-C is the same – clang parses out the doc comments and provides them to Swift-DocC.)
So updating the way that Swift documentation comments are written would be a Swift language change not a DocC change. A big benefit of this is that we ensure that Swift doc comments are compatible with all Swift tooling – instead of having fragmentation in the way doc comments work in editor integrations (like Xcode's Quick Help) vs the way they work in different documentation generation tooling (like DocC).
A good next step for Allow putting documentation after members (especially `case`) · Issue #66964 · apple/swift · GitHub would be to start a pitch thread on these forums arguing for why this change would be beneficial to the language ecosystem.
Thanks a lot (also to @krilnon and @Joseph_Heck) for the clarification.
My day job is unrelated and my spare time is heavily overbooked. Maybe next year.