SBT Scaladoc configuration for the standard library

Question

I'd like to setup ScalaDoc to link to the standard library, from SBT. I'm using 0.12.4 but I'm going to switch to 0.13 soon. Moreover, I'd like to make the setup simple by using 0.13's support.

The best option would be automatic mapping with 0.13's autoAPIMappings:

//Requires SBT 0.13. However, automatic mapping does not work for the standard library.
autoAPIMappings := true

The scala-library should support it because its pom sets info.apiURL, and that's what SBT reads.

However, this does not work. Neither String nor GenTraversable are hyperlinked. last shows that no option is added to scaladoc arguments.

So:

1. how can I fix autoAPIMappings?
2. are there alternatives?
3. I've not observed this feature working, but maybe I just need another package which sets info.apiUrl. Any packages come to mind? Google seems unhelpful, and it's unobvious how to query for maven packages with some properties, or even how to do full-text search on poms. find ~/.m2 ~/.ivy2 -name '*.pom' -type f|xargs grep info.apiUrl found no results among my 2G of local caches.

(This question might seem a dup of SBT Scaladoc Configuration, but it's for updated configuration and with a different SBT version, so the question is different; moreover, the existing answer shows a deprecated solution).

Answer 1

I know no solution for autoAPIMappings, but here are some alternatives.

1. A possible alternative, using 0.13's apiMappings, one can setup a manual mapping. On my system, last doc shows that this adds -doc-external-doc:/Users/pgiarrusso/.sbt/boot/scala-2.10.2/lib/scala-library.jar#http://www.scala-lang.org/api/2.10.2/ to the command line, and it works.

   apiMappings += (scalaInstance.value.libraryJar -> url(s"http://www.scala-lang.org/api/${scalaVersion.value}/"))
   

This requires Scaladoc 2.10.2 or later.

2. Alternatively, one can add the same option by hand. This is necessary on SBT 0.12. The main nontrivial step is to find the right library.

   In 0.13 syntax:

   scalacOptions in (Compile, doc) += s"-doc-external-doc:${scalaInstance.value.libraryJar}#http://www.scala-lang.org/api/${scalaVersion.value}/"
   

   In 0.12 syntax:

   scalacOptions in (Compile, doc) <+= (scalaVersion, scalaInstance) map { (scalaVer, scalaIn) =>
     "-doc-external-doc:" + scalaIn.libraryJar + "#http://www.scala-lang.org/api/" + scalaVer + "/"}
   

   This option still requires Scaladoc 2.10.2.

3. Finally, on older Scaladocs one can use -external-urls, even though it is less precise (and thus deprecated), as @MarkHarrah had suggested earlier.

   In 0.13 syntax:

   scalacOptions in (Compile, doc) += s"-external-urls:scala=http://www.scala-lang.org/api/${scalaVersion.value}/"
   

   In 0.12 syntax:

   scalacOptions in (Compile, doc) <+= scalaVersion map (scalaVer => "-external-urls:scala=http://www.scala-lang.org/api/" + scalaVer + "/")
   

Finally, note that in all cases occurrences of String do not become a hyperlink, maybe because of some bug with type aliases. However, other types (including GenTraversable) are hyperlinked.

Answer 2

Simply use this plugin:

https://github.com/ThoughtWorksInc/sbt-api-mappings

And the external references will be resolved.