[backport] Scaladoc: Introduce new variables to create better links t…

…o source Introduces new variables for -doc-source-url FILE_PATH_EXT - same as FILE_PATH, but including the file extension (which might be .java) FILE_EXT - the file extension (.scala or .java) FILE_LINE - containing the line number of the Symbol Fixes FILE_PATH to never contain the file extension (see scala/bug#5388)
scala · Dec 21, 2018 · 9d792e0 · 9d792e0
1 parent 329deac
commit 9d792e0
Show file tree

Hide file tree

Showing 9 changed files with 115 additions and 5 deletions.
diff --git a/build.sbt b/build.sbt
@@ -204,7 +204,7 @@ lazy val commonSettings = clearSourceAndResourceDirectories ++ publishSettings +
     "-doc-version", versionProperties.value.canonicalVersion,
     "-doc-title", description.value,
     "-sourcepath", (baseDirectory in ThisBuild).value.toString,
-    "-doc-source-url", s"https://github.com/scala/scala/tree/${versionProperties.value.githubTree}€{FILE_PATH}.scala#L1"
+    "-doc-source-url", s"https://github.com/scala/scala/tree/${versionProperties.value.githubTree}€{FILE_PATH_EXT}#L€{FILE_LINE}"
   ),
   incOptions := (incOptions in LocalProject("root")).value,
   apiURL := Some(url("http://www.scala-lang.org/api/" + versionProperties.value.mavenVersion + "/")),

diff --git a/src/scaladoc/scala/tools/nsc/doc/Settings.scala b/src/scaladoc/scala/tools/nsc/doc/Settings.scala
@@ -76,7 +76,7 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_))
   val docsourceurl = StringSetting (
     "-doc-source-url",
     "url",
-    s"A URL pattern used to link to the source file; the following variables are available: €{TPL_NAME}, €{TPL_OWNER} and respectively €{FILE_PATH}. For example, for `scala.collection.Seq`, the variables will be expanded to `Seq`, `scala.collection` and respectively `scala/collection/Seq` (without the backquotes). To obtain a relative path for €{FILE_PATH} instead of an absolute one, use the ${sourcepath.name} setting.",
+    s"A URL pattern used to link to the source file, with some variables supported: For example, for `scala.collection.Seq` €{TPL_NAME} gives `Seq`, €{TPL_OWNER} gives `scala.collection`, €{FILE_PATH} gives `scala/collection/Seq`, €{FILE_EXT} gives `.scala`, €{FILE_PATH_EXT} gives `scala/collection/Seq.scala`, and €{FILE_LINE} gives `25` (without the backquotes). To obtain a relative path for €{FILE_PATH} and €{FILE_PATH_EXT} instead of an absolute one, use the ${sourcepath.name} setting.",
     ""
   )
 

diff --git a/src/scaladoc/scala/tools/nsc/doc/model/ModelFactory.scala b/src/scaladoc/scala/tools/nsc/doc/model/ModelFactory.scala
@@ -302,13 +302,17 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
       val assumedSourceRoot  = fixPath(settings.sourcepath.value) stripSuffix "/"
 
       if (!settings.docsourceurl.isDefault)
-        inSource map { case (file, _) =>
-          val filePath = fixPath(file.path).replaceFirst("^" + assumedSourceRoot, "").stripSuffix(".scala")
+        inSource map { case (file, line) =>
+          val filePathExt = fixPath(file.path).replaceFirst("^" + assumedSourceRoot, "")
+          val (filePath, fileExt) = filePathExt.splitAt(filePathExt.indexOf(".", filePathExt.lastIndexOf("/")))
           val tplOwner = this.inTemplate.qualifiedName
           val tplName = this.name
-          val patches = new Regex("""€\{(FILE_PATH|TPL_OWNER|TPL_NAME)\}""")
+          val patches = new Regex("""€\{(FILE_PATH|FILE_EXT|FILE_PATH_EXT|FILE_LINE|TPL_OWNER|TPL_NAME)\}""")
           def substitute(name: String): String = name match {
             case "FILE_PATH" => filePath
+            case "FILE_EXT" => fileExt
+            case "FILE_PATH_EXT" => filePathExt
+            case "FILE_LINE" => line.toString
             case "TPL_OWNER" => tplOwner
             case "TPL_NAME" => tplName
           }

diff --git a/test/scaladoc/resources/doc-source-url.java b/test/scaladoc/resources/doc-source-url.java
@@ -0,0 +1,13 @@
+/*
+ * Scala (https://www.scala-lang.org)
+ *
+ * Copyright EPFL and Lightbend, Inc.
+ *
+ * Licensed under Apache License 2.0
+ * (http://www.apache.org/licenses/LICENSE-2.0).
+ *
+ * See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.
+ */
+
+public class WithSource {}
diff --git a/test/scaladoc/resources/doc-source-url.scala b/test/scaladoc/resources/doc-source-url.scala
@@ -0,0 +1,13 @@
+/*
+ * Scala (https://www.scala-lang.org)
+ *
+ * Copyright EPFL and Lightbend, Inc.
+ *
+ * Licensed under Apache License 2.0
+ * (http://www.apache.org/licenses/LICENSE-2.0).
+ *
+ * See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.
+ */
+
+class WithSource
diff --git a/test/scaladoc/run/doc-source-url-java.check b/test/scaladoc/run/doc-source-url-java.check
@@ -0,0 +1 @@
+Done.
diff --git a/test/scaladoc/run/doc-source-url-java.scala b/test/scaladoc/run/doc-source-url-java.scala
@@ -0,0 +1,39 @@
+/*
+ * Scala (https://www.scala-lang.org)
+ *
+ * Copyright EPFL and Lightbend, Inc.
+ *
+ * Licensed under Apache License 2.0
+ * (http://www.apache.org/licenses/LICENSE-2.0).
+ *
+ * See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.
+ */
+
+import java.net.URL
+
+import scala.tools.nsc.ScalaDocReporter
+import scala.tools.nsc.doc.Universe
+import scala.tools.nsc.doc.html.Page
+import scala.tools.nsc.doc.html.page.EntityPage
+import scala.tools.nsc.doc.html.page.diagram.{DiagramGenerator, DotDiagramGenerator}
+import scala.tools.nsc.doc.model._
+import scala.tools.partest.ScaladocModelTest
+
+object Test extends ScaladocModelTest {
+
+  override def resourceFile = "test/scaladoc/resources/doc-source-url.java"
+
+  override def model: Option[Universe] = newDocFactory.makeUniverse(Left(List(resourceFile)))
+
+  def scaladocSettings = "-doc-source-url file:€{FILE_PATH}||€{FILE_EXT}||€{FILE_PATH_EXT}||€{FILE_LINE}"
+
+  def testModel(rootPackage: Package) = {
+    import access._
+
+    val clazz = rootPackage._class("WithSource")
+
+    val expect = s"file:test/scaladoc/resources/doc-source-url||.java||test/scaladoc/resources/doc-source-url.java||13"
+    assert(clazz.sourceUrl.contains(new URL(expect)), s"got ${clazz.sourceUrl}")
+  }
+}
diff --git a/test/scaladoc/run/doc-source-url.check b/test/scaladoc/run/doc-source-url.check
@@ -0,0 +1 @@
+Done.
diff --git a/test/scaladoc/run/doc-source-url.scala b/test/scaladoc/run/doc-source-url.scala
@@ -0,0 +1,39 @@
+/*
+ * Scala (https://www.scala-lang.org)
+ *
+ * Copyright EPFL and Lightbend, Inc.
+ *
+ * Licensed under Apache License 2.0
+ * (http://www.apache.org/licenses/LICENSE-2.0).
+ *
+ * See the NOTICE file distributed with this work for
+ * additional information regarding copyright ownership.
+ */
+
+import java.net.URL
+
+import scala.tools.nsc.ScalaDocReporter
+import scala.tools.nsc.doc.Universe
+import scala.tools.nsc.doc.html.Page
+import scala.tools.nsc.doc.html.page.EntityPage
+import scala.tools.nsc.doc.html.page.diagram.{DiagramGenerator, DotDiagramGenerator}
+import scala.tools.nsc.doc.model._
+import scala.tools.partest.ScaladocModelTest
+
+object Test extends ScaladocModelTest {
+
+  override def resourceFile = "test/scaladoc/resources/doc-source-url.scala"
+
+  override def model: Option[Universe] = newDocFactory.makeUniverse(Left(List(resourceFile)))
+
+  def scaladocSettings = "-doc-source-url file:€{FILE_PATH}||€{FILE_EXT}||€{FILE_PATH_EXT}||€{FILE_LINE}"
+
+  def testModel(rootPackage: Package) = {
+    import access._
+
+    val clazz = rootPackage._class("WithSource")
+
+    val expect = s"file:test/scaladoc/resources/doc-source-url||.scala||test/scaladoc/resources/doc-source-url.scala||13"
+    assert(clazz.sourceUrl.contains(new URL(expect)), s"got ${clazz.sourceUrl}")
+  }
+}