All good questions, but I think they’re mostly answered by this feature being opt-in by package authors. If we don't find a .spi.yml file with the relevant keys, we don't generate docs.
As Sven mentioned above we’re going to be adding a feature where authors can tell us where their official docs hosting is and we’ll send people there. We don’t yet have issues created for everything that’s going to make up the “completed” feature (is there ever such a thing?), but this is certainly one that we’ll implement.
Yep, versioning is really important and as soon as we have it done we'll be switching the default "Documentation" link for a package to show the latest stable docs, rather than those from the default branch.
In cases where authors prefer not to add the .spi.yml file to their repository and would still like to have their docs hosted by us we have a mechanism in place to do so.
for completeness, swiftinit.org also hosts package references which overlap with the ones served by swiftpackageindex.com, swift.org, and apple.com. many projects like SwiftNIO and Vapor also host their own package-specific references.
although basic historical archiving is straightforward to acheive, true documentation versioning is extremely difficult to implement when you add URL stability as a requirement.
moreover, certain packages like swift-syntax contain both a large number of symbols, and a large number of tag releases, which makes indexing and serving this kind of content a significant engineering task in and of itself. although most packages do not vend enough API or release often enough to strain the documentation service provider, a handful of “fat” packages like swift-syntax are currently blocking this feature, at least for swiftinit.org.
i believe this was previously discussed at the last meeting of the documentation working group.
