One of the primary benefits of open-source software is that users can access the source code if the documentation isn't complete, not clear enough or just out of curiosity.
But often, documentation is the gateway through which users will come so it's only natural that you'd expect to be able to hop straight from the documentation to the source code. And in fact, Jazzy and many other documentation generation systems support this. For example look at the Show on Github links in the SwiftNIO API docs.
Personally, this is how I always navigate the project if I just have to check some detail: I find the docs which is easy and then hop over straight to Github. By the way, that also invites users to improve the documentation because they can click the edit button on Github right where the docs sent them and add the missing details.
I understand that DocC doesn't do this today which is a shame. How would everybody feel about adding this feature?
This is incredibly valuable IMHO and I agree adding it would provide lots of value.
I agree on both accounts:
this helps get users to the source and able to contribute fixes
it helps general "the source is not scary" as it is easy to hop back and forth from docs and sources
If there needs to be any "others are doing it" then scaladoc does it and it's been an invaluable tool, especially since it links to the right tag of the exact version one is browsing the documentation for:
Which points at the right tag and exact line of the declaration: https://github.com/akka/akka/blob/v2.6.18/akka-actor/src/main/scala/akka/actor/ActorRef.scala#L108
I always found this to be a very valuable feature and would love us to catch up on this front
Yeah, same for Haskell (example). Although I'll say that the Haskell docs have a copy of the source instead of linking to Github/... which is better than nothing but at least having the option to link directly into the upstream repo is best IMHO.
Indeed, SymbolKit.Symbol.Location and the compiler-generated symbol graph JSON already include file locations which could be used to support this sort of feature.
I believe the only remaining design bit would be to figure out how best to provide the url prefix for the file path and version. For example, the equivalent of Jazzy's --github-file-prefix https://github.com/apple/swift-nio/tree/$version.
I think it would be very helpful, and I'd like to have the same available for my (open source) libraries. So count me in as positive for a feature such as this.
Because swift packages support any git hosting, I suspect that whatever mechanism to determine an appropriate URL path prefix is something that would need to be passed in via command line, and that could abstract the hosting scenario (github, gitlab, etc) as well as the pathing for release (branch name, tag name, etc).
There was a prior comment in these forums about a desire to have multiple versions of documentation available as a library progresses, and while less important to me personally, I think that's an interesting use case.
Agreed, this would be a fantastic improvement for open source projects. I'm wondering where that link should be displayed on the website. Somewhere near the declaration would certainly make sense, as the declaration is already in some fashion a snapshot of the source code. A "Show source code" link under the declaration could potentially work.
As a plain data point, jazzy defines a few command line options for those links:
% jazzy --help
Usage: jazzy
[...]
--source-host github | gitlab | bitbucket
The source-code hosting site to be linked from documentation.
This setting affects the logo image and link format.
Default: 'github'
--source-host-url URL URL to link from the source host's logo.
For example https://github.com/realm/realm-cocoa
--source-host-files-url PREFIX
The base URL on the source host of the project's files, to link from individual declarations.
For example https://github.com/realm/realm-cocoa/tree/v0.87.1
The generated links contain the line range for the whole declaration (example: https://github.com/groue/GRDB.swift/tree/v5.21.0/GRDB/Core/DatabaseQueue.swift#L35-L48).
Note that GitLab uses a different convention for line-range anchors (example: https://gitlab.com/Mordil/RediStack/-/blob/1.2.1/Sources/RediStack/RedisKey.swift#L36-38).
