如何使用 apiMappings 链接 Java API 类？答案

【问题标题】：How to link Java API classes using apiMappings?如何使用 apiMappings 链接 Java API 类？
【发布时间】：2014-06-17 10:43:52
【问题描述】：

如何使用apiMappings 链接到 sbt 中的 Java 类？这是我下面的代码，它适用于各种依赖项，但我不清楚如何链接到 Java 标准库类？

apiMappings ++= {
  def findManagedDependency(organization: String, name: String): Option[File] = {
    (for {
      entry <- (fullClasspath in Runtime).value ++ (fullClasspath in Test).value
      module <- entry.get(moduleID.key) if module.organization == organization && module.name.startsWith(name)
    } yield entry.data).headOption
  }
  val links = Seq(
    findManagedDependency("org.scala-lang", "scala-library").map(d => d -> url(s"http://www.scala-lang.org/api/$scalaVsn/")),
    findManagedDependency("com.typesafe.akka", "akka-actor").map(d => d -> url(s"http://doc.akka.io/api/akka/$akkaVersion/")),
    findManagedDependency("com.typesafe", "config").map(d => d -> url("http://typesafehub.github.io/config/latest/api/")),
    findManagedDependency("com.fasterxml.jackson.core", "jackson-core").map(d => d -> url("http://fasterxml.github.io/jackson-core/javadoc/2.3.1/")),
    findManagedDependency("io.spray", "spray-http").map(d => d -> url("http://spray.io/documentation/1.1-SNAPSHOT/api/")),
    findManagedDependency("io.spray", "spray-routing").map(d => d -> url("http://spray.io/documentation/1.1-SNAPSHOT/api/")),
    findManagedDependency("org.slf4j", "slf4j-api").map(d => d -> url("http://www.slf4j.org/api/")),
    findManagedDependency("com.typesafe.akka", "akka-testkit").map(d => d -> url(s"http://doc.akka.io/api/akka/$akkaVersion/")),
    findManagedDependency("org.specs2", "specs2").map(d => d -> url(s"http://etorreborre.github.io/specs2/api/SPECS2-$specs2Version/"))
  )
  links.collect { case Some(d) => d }.toMap
}

【问题讨论】：

您要链接 Java 库还是 Scala 标准库？如果是Java，这道题是stackoverflow.com/questions/16934488的重复题，Scaladoc基本不支持。
@EugeneYokota 我正在尝试链接到标准 Java 库。在 2.11 之前，我使用了“-external-urls”，效果很好，但该选项不再可用。没有合法的方法可以做到这一点了吗？这似乎......不是最佳选择。
我对@987654322@ 的回答中缺少您的用例所需的内容？你可以在执行doc 之后执行last doc 来查看缺少哪些选项并与不同版本的Scala 进行比较吗？我真的需要更多的输入来处理用例。
注意到您正在使用可以大致称为“findManagedDependency 模式”的东西，您可能会对in an answer I've given to a related question that makes these mappings more generic（并且可重用）感兴趣。

标签： sbt scaladoc

【解决方案1】：

使用来自How to link classes from JDK into scaladoc-generated doc? 的解决方案，即将以下内容添加到apiMappings：

apiMappings += (
    file("/Library/Java/JavaVirtualMachines/jdk1.8.0_11.jdk/Contents/Home/jre/lib/rt.jar") -> 
    url("http://docs.oracle.com/javase/8/docs/api")
)

而fixJavaLinksTask 任务将在build.sbt 中完成其余的工作：

import scala.util.matching.Regex.Match

autoAPIMappings := true

// builds -doc-external-doc
apiMappings += (
    file("/Library/Java/JavaVirtualMachines/jdk1.8.0_11.jdk/Contents/Home/jre/lib/rt.jar") -> 
    url("http://docs.oracle.com/javase/8/docs/api")
)

lazy val fixJavaLinksTask = taskKey[Unit](
    "Fix Java links - replace #java.io.File with ?java/io/File.html"
)

fixJavaLinksTask := {
  println("Fixing Java links")
  val t = (target in (Compile, doc)).value
  (t ** "*.html").get.filter(hasJavadocApiLink).foreach { f => 
    println("fixing " + f)
    val newContent = javadocApiLink.replaceAllIn(IO.read(f), fixJavaLinks)
    IO.write(f, newContent)
  }
}

val fixJavaLinks: Match => String = m =>
    m.group(1) + "?" + m.group(2).replace(".", "/") + ".html"

val javadocApiLink = """\"(http://docs\.oracle\.com/javase/8/docs/api/index\.html)#([^"]*)\"""".r

def hasJavadocApiLink(f: File): Boolean = (javadocApiLink findFirstIn IO.read(f)).nonEmpty

fixJavaLinksTask <<= fixJavaLinksTask triggeredBy (doc in Compile)

【讨论】：

【解决方案2】：

您可以找到我对this question 的答案。

该答案与此处发布的其他答案之间的主要区别在于，rt.jar 的位置由运行时确定，而不是硬编码。

【讨论】：