javase - api java 8 oracle

¿Cómo vincular clases de JDK en doc generado por scaladoc?

Question

Estoy tratando de vincular las clases del JDK con el documento generado por scaladoc. He usado la -doc-external-doc de scaladoc 2.10.1 pero sin éxito.

Estoy usando -doc-external-doc:/usr/lib/jvm/java-7-openjdk-amd64/jre/lib/rt.jar#http://docs.oracle.com/javase/7/docs/api/ , pero obtengo enlaces como index.html#java.io.File lugar de index.html?java/io/File.html . Parece que esta opción solo funciona para documentos generados por scaladoc.

¿Perdí una opción en scaladoc o debo completar una solicitud de función?

He configurado sbt de la siguiente manera:

 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"

Nota: He visto la Opts.doc.externalAPI en el próximo sbt 0.13. Creo que una buena adición (no estoy seguro de si es posible) sería pasar un ModuleID lugar de un File . La utilidad podría averiguar qué archivo corresponde al ModuleID .

Answer 1

Tomé la respuesta de @ jacek-laskowski y la modifiqué para que evitara las cadenas codificadas y pudiera usarse para cualquier número de bibliotecas de Java, no solo la estándar.

Edición: la ubicación de rt.jar ahora se determina a partir del tiempo de ejecución mediante sun.boot.class.path y no tiene que estar codificada.

Lo único que necesita modificar es el mapa, al que he llamado externalJavadocMap en lo siguiente:

import scala.util.matching.Regex
import scala.util.matching.Regex.Match

val externalJavadocMap = Map(
  "owlapi" -> "http://owlcs.github.io/owlapi/apidocs_4_0_2/index.html"
)

/*
 * The rt.jar file is located in the path stored in the sun.boot.class.path system property.
 * See the Oracle documentation at http://docs.oracle.com/javase/6/docs/technotes/tools/findingclasses.html.
 */
val rtJar: String = System.getProperty("sun.boot.class.path").split(java.io.File.pathSeparator).collectFirst {
  case str: String if str.endsWith(java.io.File.separator + "rt.jar") => str
}.get // fail hard if not found

val javaApiUrl: String = "http://docs.oracle.com/javase/8/docs/api/index.html"

val allExternalJavadocLinks: Seq[String] = javaApiUrl +: externalJavadocMap.values.toSeq

def javadocLinkRegex(javadocURL: String): Regex = ("""/"(/Q""" + javadocURL + """/E)#([^"]*)/"""").r

def hasJavadocLink(f: File): Boolean = allExternalJavadocLinks exists {
  javadocURL: String => 
    (javadocLinkRegex(javadocURL) findFirstIn IO.read(f)).nonEmpty
}

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

/* You can print the classpath with `show compile:fullClasspath` in the SBT REPL.
 * From that list you can find the name of the jar for the managed dependency.
 */
lazy val documentationSettings = Seq(
  apiMappings ++= {
    // Lookup the path to jar from the classpath
    val classpath = (fullClasspath in Compile).value
    def findJar(nameBeginsWith: String): File = {
      classpath.find { attributed: Attributed[File] => (attributed.data ** s"$nameBeginsWith*.jar").get.nonEmpty }.get.data // fail hard if not found
    }
    // Define external documentation paths
    (externalJavadocMap map {
      case (name, javadocURL) => findJar(name) -> url(javadocURL)
    }) + (file(rtJar) -> url(javaApiUrl))
  },
  // Override the task to fix the links to JavaDoc
  doc in Compile <<= (doc in Compile) map {
    target: File =>
      (target ** "*.html").get.filter(hasJavadocLink).foreach { f => 
        //println(s"Fixing $f.")
        val newContent: String = allExternalJavadocLinks.foldLeft(IO.read(f)) {
          case (oldContent: String, javadocURL: String) =>
            javadocLinkRegex(javadocURL).replaceAllIn(oldContent, fixJavaLinks)
        }
        IO.write(f, newContent)
      }
      target
  }
)

Estoy usando SBT 0.13.8.

Answer 2

Yo uso sbt 0.13.5.

No hay una manera inmediata de tener la característica de tener enlaces Javadoc dentro de scaladoc. Y, según mi entendimiento, no es culpa de sbt, sino de la forma en que funciona scaladoc. Como jsuereth señaló en su comentario , debe informar a scaladoc.

Sin embargo, se me ocurrió una solución alternativa: después de procesar el doc scaladoc generado para que las URL de Java se reemplacen para formar los enlaces Javadoc adecuados.

El archivo scaladoc.sbt se debe colocar dentro de un proyecto sbt y cada vez que se ejecuta la tarea doc , se fixJavaLinksTask el postproceso a través de la tarea fixJavaLinksTask .

NOTA Hay muchos caminos codificados, así que utilícelo con precaución ( también conocido como pulir como mejor le parezca).

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)