如何将 JDK 中的类链接到 scaladoc 生成的文档中?

2022-01-24 00:00:00 scala java sbt scaladoc

我正在尝试将 JDK 中的类链接到 scaladoc 生成的文档中.我使用了 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"

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

相关文章