Hi everyone, I'm happy to propose a new functionality to link symbol documentation pages back to their source code. This is a feature a lot of you had requested, here's the link to the original post by @johannesweiss. The goal of this feature is to make it easier for developers to quickly locate the lines where a symbol is declared in.
The source file link will be placed under the declaration code snippet.
This is an opt-in feature that you use via the following two new flags:
swift package generate-documentation \
--source-service github \ // GitHub, GitLab, or BitBucket
--source-service-base-url https://github.com/<org>/<repo>/blob/main
Documentation pages for symbols automatically gain a link to the declaration in source:
I think there's a lot of value in hardcoding URL formats for popular hosting services like GitHub, so that users can use this functionality without needing to know how GitHub formats its URLs. The placeholder approach you propose is more flexible though as a future enhancement, e.g., to support source services other than the ones this feature supports natively.
Yes, we're unblocked on this. Our main limiting factor right now is team bandwidth, as we'd like to extract the documentation from the swift-nio repo to avoid it continuing to bloat the repo clone time as the current docs do.