thoughtworksinc / sbt-api-mappings

An Sbt plugin that fills apiMappings for common Scala libraries.

sbt-api-mappings

sbt-api-mappings is a sbt plugin that fills apiMappings for common Scala libraries.

Motivation

Sometimes when you wrote ScalaDoc for your own classes, you may want to reference to documentation in some other libraries.

For example:

/**
 * My own class, which works with [[scala.Option]] and [[scalaz.Monad]].
 */
class MyClass(optionMonad: scalaz.Monad[Option])

Unfortunately when running doc command in Sbt, you will receive a warning and the link would not be created.

/path/to/MyClass.scala:3: Could not find any member to link for "scala.Option".

This plugin resolves the problem.

Usage

Step 1: Add the following lines in your project/plugins.sbt:

addSbtPlugin("com.thoughtworks.sbt-api-mappings" % "sbt-api-mappings" % "latest.release")

Note that sbt-api-mappings 1.x requires sbt 0.13.x, sbt-api-mappings 2.x requires sbt 1.x.

Step 2: Reload the Sbt configuration:

> reload

Step 3: Generate your API documentation:

> doc

Now, open the API documentation in your browser, and you will find the links to the scala.Option and scalaz.Monad's documentation in your MyClass page.

sbt-api-mappings's Issues

Plugin fails with milestone and RC scala versions

When using this plugin, and cross-compiling against scala 2.12.0-RC2, I get this error:

scala.MatchError: scala-compiler-2.12.0-RC2.jar (of class java.lang.String)
    at com.thoughtworks.sbtApiMappings.ApiMappings$$anonfun$projectSettings$3$$anonfun$apply$2.apply(ApiMappings.scala:41)
    at com.thoughtworks.sbtApiMappings.ApiMappings$$anonfun$projectSettings$3$$anonfun$apply$2.apply(ApiMappings.scala:39)

The regex ScalaLibraryRegex doesn't match M* or RC* versions.

Update docs to point to v0.2.0

Change this:

addSbtPlugin("com.thoughtworks.sbt-api-mappings" % "sbt-api-mappings" % "0.1.0")

to this:

addSbtPlugin("com.thoughtworks.sbt-api-mappings" % "sbt-api-mappings" % "0.2.0")

Be able to run on JDK9

In Akka we're trying to release for JDK9 already and are working on the entire plugin ecosystem to allow this. I found that there's a missing case in this plugin too which makes it not usable with JDK9:

[error] scala.MatchError: 9 (of class java.lang.String)
[error] 	at com.thoughtworks.sbtApiMappings.BootstrapApiMappings$.$anonfun$globalSettings$1(BootstrapApiMappings.scala:28)
[error] 	at sbt.internal.util.Init$Value.$anonfun$apply$3(Settings.scala:804)

Java 11 URLs contain module name

The current Javadocs for JDK 11 even require the module name in the URL:

• eg contain java.base:

https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/Duration.html

The current mapping issued by this plugin lacks the module name and creates

https://docs.oracle.com/en/java/javase/11/docs/api/java/time/Duration.html

handle linking to Javadoc for Java standard library

would be cool. as per e.g. http://stackoverflow.com/questions/16934488/how-to-link-classes-from-jdk-into-scaladoc-generated-doc

Enable plugin automatically?

Would you make the plugin auto-enabled?

From, it looks like adding:

override def trigger = allRequirements

would be enough for that.