Add canonical URL tag to scala API doc pages

[lajnakjjfn]

https://publicobject.com/2017/02/14/canonical-urls-for-javadocs/ reminded me that the described issue seems to also be present for the docs at http://www.scala-lang.org/api.

The issue being, when e.g. searching for 'scala bigint', Google shows links for the 2.7.4 and 2.12.0 API docs, but not for the 'current' version.

Would it make sense to insert canonical URL tags in the future API doc pages on scala-lang.org/api, or even retroactively in the existing versions?

[SethTisue]

yes, I believe a pull request that added this would be welcome

but, it isn't obvious to me without doing a little research if this should be a change to the Scaladoc tool, or a change to https://github.com/scala/scala-dist, or what

applying the change retroactively would require running a script on the machine that serves scala-lang.org, but we could certainly do that too — if the pull request included such a script, which had been tested first locally, that would be super-awesome

[mslinn]

Please consider this an actionable request for supporting the Scala-related educational community.

Most of the Scaladoc links in our 2 Scala courses broke with the Scala 2.13 release (~350 links in 110 lectures) because the URLs for method-level docs changed. This was not a problem for previous Scala releases. Canonical URLs would have prevented that, and could also provide a universally accepted shortening method so bazillion-character-long URLs would be no longer be generated.

Even though I wrote a script to generate SQL commands to update the transcript database, many URLs still need to be hand-tweaked.

[Jasper-M]

Most of the Scaladoc links in our 2 Scala courses broke with the Scala 2.13 release (~350 links in 110 lectures) because the URLs for method-level docs changed. This was not a problem for previous Scala releases. Canonical URLs would have prevented that

I'm not sure how you would maintain this across different Scala version (except manually for each class and method). The reason the urls changed is that classes changed packages and methods changed signatures.

Also note that although this issue is closed because scaladoc supports setting a canonical url, I don't think that the scaladoc of the standard library already contains canonical urls.

[mslinn]

I don't think I did a good job of explaining myself.

• The autogenerated URLs are unwieldy, so a standard algorithm for shortening them would help
• Several different URL generation mechanisms have been used over the years. I'm asking for a stable mechanism, which I called "canonical" per the link I provided.