如何将JDK中的类链接到scaladoc生成的doc？ [英] How to link classes from JDK into scaladoc-generated doc?

问题描述

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

I'm trying to link classes from the JDK into the scaladoc-generated doc. I've used the -doc-external-doc option of scaladoc 2.10.1 but without success.

我正在使用 -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生成的文档。

I'm using -doc-external-doc:/usr/lib/jvm/java-7-openjdk-amd64/jre/lib/rt.jar#http://docs.oracle.com/javase/7/docs/api/, but I get links such as index.html#java.io.File instead of index.html?java/io/File.html. Seems like this option only works for scaladoc-generated doc.

我是否错过了scaladoc中的选项，还是应填写功能请求？

Did I miss an option in scaladoc or should I fill a feature request?

我已按如下方式配置sbt：

I've configured sbt as follows:

 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"

注意：我见过 Opts.doc.externalAPI util即将推出的sbt 0.13。我认为一个很好的补充（不确定是否可能）将传递 ModuleID 而不是文件。 util会找出哪个文件对应 ModuleID 。

Note: I've seen the Opts.doc.externalAPI util in the upcoming sbt 0.13. I think a nice addition (not sure if it's possible) would be to pass a ModuleID instead of a File. The util would figure out which file corresponds to the ModuleID.

推荐答案

我使用sbt 0.13.5。

I use sbt 0.13.5.

没有开箱即用的方法可以在scaladoc中使用Javadoc链接。正如我的理解所说，这不是sbt的错，而是scaladoc的工作方式。正如 Josh 在他的评论中指出的那样你应该向scaladoc报告。

There's no out-of-the-box way to have the feature of having Javadoc links inside scaladoc. And as my understanding goes, it's not sbt's fault, but the way scaladoc works. As Josh pointed out in his comment You should report to scaladoc.

然而有一个变通方法我提出了 - 后处理 doc 生成的scaladoc，以便替换Java URL以形成正确的Javadoc链接。

There's however a workaround I came up with - postprocess the doc-generated scaladoc so the Java URLs get replaced to form proper Javadoc links.

文件 scaladoc.sbt 应放在sbt项目中，每当执行 doc 任务时，通过 fixJavaLinksTask进行后处理任务开始。

The file scaladoc.sbt should be placed inside a sbt project and whenever doc task gets executed, the postprocessing via fixJavaLinksTask task kicks in.

注意有很多硬编码路径所以请谨慎使用（ aka 做你认为合适的抛光。）

NOTE There are lots of hardcoded paths so use it with caution (aka do the polishing however you see fit).

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)

这篇关于如何将JDK中的类链接到scaladoc生成的doc？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！