java - 如何将 JDK 中的类链接到 scaladoc 生成的文档中？

Question

我正在尝试将 JDK 中的类链接到 scaladoc 生成的文档中。我使用了 scaladoc 2.10.1 的 -doc-external-doc 选项，但没有成功。

我正在使用 -doc-external-doc:/usr/lib/jvm/java-7-openjdk-amd64/jre/lib/rt.jar#http://docs.oracle.com/javase/7/docs/api/，但我得到的链接是 index.html#java.io.File 而不是 index.html?java/io/File。 html。似乎此选项仅适用于 scaladoc 生成的文档。

我错过了 scaladoc 中的一个选项还是应该填写一个功能请求？

我对 sbt 的配置如下:

 scalacOptions in (Compile,doc) += "-doc-external-doc:/usr/lib/jvm/java-7-openjdk-amd64/jre/lib/rt.jar#http://docs.oracle.com/javase/7/docs/api"

注意:我在即将发布的 sbt 0.13 中看到了 Opts.doc.externalAPI 实用程序。我认为一个很好的补充(不确定是否可能)是传递 ModuleID 而不是 File。该实用程序将找出哪个文件对应于 ModuleID。

Answer 1

我使用 sbt 0.13.5。

没有开箱即用的方式来拥有在 scaladoc 中包含 Javadoc 链接的功能。根据我的理解，这不是 sbt 的错，而是 scaladoc 的工作方式。如Josh在他的评论中指出 You should report to scaladoc.

不过，我想出了一个解决方法 - 对 doc 生成的 scaladoc 进行后处理，以便替换 Java URL 以形成正确的 Javadoc 链接。

文件 scaladoc.sbt 应该放在一个 sbt 项目中，每当 doc 任务被执行时，通过 fixJavaLinksTask 任务的后处理就会启动.

注意有很多硬编码路径，因此请谨慎使用(aka 可根据您的需要进行优化)。

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)