如何讓Scaladoc鏈接到外部API？

01-27

有時候，給你的Scala代碼編寫Scaladoc API文檔時，你可能會需要引用其他庫的Scaladoc API文檔。

比如你可能會這樣寫：

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

根據Scaladoc語法文檔，以上注釋可以生成兩個網頁鏈接，指向scala.Option和scalaz.Monad的API文檔。

然而這根本沒用。如果你用Sbt生成文檔：

sbt doc

那麼你會收到Scala編譯器警告如下：

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

生成的文檔中根本沒有鏈接。

這是因為，Scala編譯器默認只能為同一個庫的內部引用生成鏈接，外部庫的文檔鏈接，還需要額外設置。

這種情況下，你需要使用一個Sbt插件：sbt-api-mappings。在 project/plugins.sbt 中加入以下設置：

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

然後重新執行sbt doc。Scala編譯器就會在文檔中生成兩個網頁鏈接，分別指向scala.Option和scalaz.Monad官方網站上的API文檔。

注意，現在文檔和API簽名中涉及的外部API，全部都有了網頁鏈接。