Add integration tests for external location providers. Add test for annotations for type parameter in methods.

Author: pikinier20

scala3doc-testcases/src/tests/externalLocations/javadoc.scala

@@ -0,0 +1,12 @@
+package tests.externalJavadoc
+
+import java.util._
+
+class Test {
+  def a: Map.Entry[String, String] = ???
+
+  def b: java.util.Map[String, Int] = ???
+
+  def c: java.util.stream.Stream.Builder[String] = ???
+}
+

scala3doc-testcases/src/tests/externalLocations/scala3doc.scala

@@ -0,0 +1,12 @@
+package tests.externalScala3doc
+
+import scala.util.matching._
+
+class Test {
+  def a: String = ???
+
+  def b: Map[String, Int] = ???
+
+  def c: Regex.Match = ???
+}
+

scala3doc-testcases/src/tests/externalLocations/scaladoc.scala

@@ -0,0 +1,12 @@
+package tests.externalScaladoc
+
+import scala.util.matching._
+
+class Test {
+  def a: String = ???
+
+  def b: Map[String, Int] = ???
+
+  def c: Regex.Match = ???
+}
+

scala3doc-testcases/src/tests/specializedSignature.scala

@@ -8,4 +8,7 @@ trait AdditiveMonoid[@specialized(Int, Long, Float, Double) A]
 {
   def a: A
    = ???
+
+  def b[@specialized(Int, Float) B]: B
+   = ???
 }

scala3doc/src/dotty/dokka/ExternalDocLink.scala

@@ -2,7 +2,7 @@ package dotty.dokka
 
 import java.net.URL
 import scala.util.matching._
-import scala.util.Try
+import scala.util.{ Try, Success, Failure }
 
 case class ExternalDocLink(
   originRegexes: List[Regex],
@@ -18,25 +18,23 @@ enum DocumentationKind:
   case Scala3doc extends DocumentationKind
 
 object ExternalDocLink:
-  def parse(mapping: String)(using CompilerContext): Option[ExternalDocLink] =
-    def fail(msg: String) =
-      report.warning(s"Unable to parocess external mapping $mapping. $msg")
-      None
+  def parse(mapping: String): Either[String, ExternalDocLink] =
+    def fail(msg: String) = Left(s"Unable to process external mapping $mapping. $msg")
 
-    def tryParse[T](descr: String)(op: => T): Option[T] = try Some(op) catch
-      case e: RuntimeException =>
-        report.warn(s"Unable to parse $descr", e)
-        None
+    def tryParse[T](descr: String)(op: => T): Either[String, T] = Try(op) match {
+      case Success(v) => Right(v)
+      case Failure(e) => fail(s"Unable to parse $descr. Exception $e occured")
+    }
 
     def parsePackageList(elements: List[String]) = elements match
-     case List(urlStr) => tryParse("packageList")(Option(URL(urlStr)))
-     case Nil => Some(None)
+     case List(urlStr) => tryParse("packageList")(Some(URL(urlStr)))
+     case Nil => Right(None)
      case other => fail(s"Provided multiple package lists: $other")
 
     def doctoolByName(name: String) = name match
-      case "javadoc" => Some(DocumentationKind.Javadoc)
-      case "scaladoc" => Some(DocumentationKind.Scaladoc)
-      case "scala3doc" => Some(DocumentationKind.Scala3doc)
+      case "javadoc" => Right(DocumentationKind.Javadoc)
+      case "scaladoc" => Right(DocumentationKind.Scaladoc)
+      case "scala3doc" => Right(DocumentationKind.Scala3doc)
       case other => fail(s"Unknown doctool: $other")
 
 
@@ -48,10 +46,10 @@ object ExternalDocLink:
           doctool <- doctoolByName(docToolStr)
           packageList <- parsePackageList(rest)
         } yield ExternalDocLink(
-          List(regex),
-          url,
-          doctool,
-          packageList
-        )
+            List(regex),
+            url,
+            doctool,
+            packageList
+          )
       case _ =>
         fail("Accepted format: `regexStr::docToolStr::urlStr[::rest]`")

scala3doc/src/dotty/dokka/Scala3docArgs.scala

@@ -114,7 +114,13 @@ object Scala3docArgs:
       }
     }
     val externalMappings =
-      externalDocumentationMappings.get.flatMap(ExternalDocLink.parse)
+      externalDocumentationMappings.get.flatMap( s =>
+          ExternalDocLink.parse(s).fold(left => {
+            report.warning(left)
+            None
+          }, right => Some(right)
+        )
+      )
 
     unsupportedSettings.filter(s => s.get != s.default).foreach { s =>
       report.warning(s"Setting ${s.name} is currently not supported.")

scala3doc/src/dotty/dokka/location/ScalaExternalLocationProvider.scala

@@ -35,21 +35,23 @@ class ScalaExternalLocationProvider(
     case DocumentationKind.Scala3doc => constructPathForScala3doc(dri)
   }
 
+  //TODO #263: Add anchor support
+
   private def constructPathForJavadoc(dri: DRI): String = {
     val location = "\\$+".r.replaceAllIn(dri.location.replace(".","/"), _ => ".")
     val origin = originRegex.findFirstIn(dri.extra)
     val anchor = dri.anchor
-    docURL + location + extension + anchor.fold("")(a => s"#$a")
+    docURL + location + extension
   }
 
   private def constructPathForScaladoc(dri: DRI): String = {
     val location = dri.location.replace(".","/")
     val anchor = dri.anchor
-    docURL + location + extension + anchor.fold("")(a => s"#$a")
+    docURL + location + extension
   }
 
   private def constructPathForScala3doc(dri: DRI): String = {
     val location = dri.location.replace(".","/")
     val anchor = dri.anchor
-    docURL + location + anchor.fold(extension)(a => s"/$a$extension")
+    docURL + location + extension
   }

scala3doc/test/dotty/dokka/ExternalLocationProviderIntegrationTest.scala

@@ -0,0 +1,78 @@
+package dotty.dokka
+
+import scala.io.Source
+import scala.jdk.CollectionConverters._
+import scala.util.matching.Regex
+import dotty.dokka.test.BuildInfo
+import java.nio.file.Path;
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.pages.{RootPageNode, PageNode, ContentPage, ContentText, ContentNode, ContentComposite}
+import org.jsoup.Jsoup
+
+class JavadocExternalLocationProviderIntegrationTest extends ExternalLocationProviderIntegrationTest(
+  "externalJavadoc",
+  List(".*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/"),
+  List(
+    "https://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.Builder.html",
+    "https://docs.oracle.com/javase/8/docs/api/java/util/Map.Entry.html",
+    "https://docs.oracle.com/javase/8/docs/api/java/util/Map.html"
+  )
+)
+
+class ScaladocExternalLocationProviderIntegrationTest extends ExternalLocationProviderIntegrationTest(
+  "externalScaladoc",
+  List(".*scala.*::scaladoc::https://www.scala-lang.org/api/current/"),
+  List(
+    "https://www.scala-lang.org/api/current/scala/util/matching/Regex$$Match.html",
+    "https://www.scala-lang.org/api/current/scala/Predef$.html",
+    "https://www.scala-lang.org/api/current/scala/collection/immutable/Map.html"
+  )
+)
+
+class Scala3docExternalLocationProviderIntegrationTest extends ExternalLocationProviderIntegrationTest(
+  "externalScala3doc",
+  List(".*scala.*::scala3doc::https://dotty.epfl.ch/api/"),
+  List(
+    "https://dotty.epfl.ch/api/scala/collection/immutable/Map.html",
+    "https://dotty.epfl.ch/api/scala/Predef$.html",
+    "https://dotty.epfl.ch/api/scala/util/matching/Regex$$Match.html"
+  )
+)
+
+
+abstract class ExternalLocationProviderIntegrationTest(name: String, mappings: Seq[String], expectedLinks: Seq[String]) extends ScaladocTest(name):
+  override def args = super.args.copy(
+    externalMappings = mappings.flatMap( s =>
+          ExternalDocLink.parse(s).fold(left => None, right => Some(right)
+        )
+      ).toList
+  )
+
+  def assertions = Assertion.AfterRendering { (root, ctx) =>
+    given DokkaContext = ctx
+    val output = summon[DocContext].args.output.toPath.resolve("api")
+    val linksBuilder = List.newBuilder[String]
+
+    def processFile(path: Path): Unit =
+      val document = Jsoup.parse(IO.read(path))
+      val content = document.select(".documentableElement").forEach { elem =>
+        val hrefValues = elem.select("a").asScala.map { a =>
+          a.attr("href")
+        }
+        linksBuilder ++= hrefValues
+      }
+
+
+    IO.foreachFileIn(output, processFile)
+    val links = linksBuilder.result
+    val errors = expectedLinks.flatMap(expect => Option.when(!links.contains(expect))(expect))
+    if !errors.isEmpty then {
+      val reportMessage =
+      "External location provider integration test failed.\n" +
+      "Missing links:\n"
+      + errors.mkString("\n","\n","\n")
+      + "Found links:" + links.mkString("\n","\n","\n")
+      reportError(reportMessage)
+    }
+  } :: Nil
+

scala3doc/test/dotty/dokka/ScaladocTest.scala

@@ -20,7 +20,7 @@ abstract class ScaladocTest(val name: String):
     folder.create()
     folder
 
-  private def args = Scala3doc.Args(
+  def args = Scala3doc.Args(
       name = "test",
       tastyFiles = tastyFiles(name),
       output = getTempDir().getRoot,