Merge pull request #10833 from lampepfl/scala3doc-fixes

Scala3doc: Add support for annotations in type parameters, add tests for external location providing, minor fixes

Author: romanowski

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/objectSignatures.scala

@@ -15,5 +15,9 @@ object Base
 
 object A2 extends A[String] with C
 
+object <
+
+object >
+
 // We are not going to add final below
 // final object B

scala3doc-testcases/src/tests/specializedSignature.scala

@@ -0,0 +1,14 @@
+package tests
+
+package specializedSignature
+
+import scala.{specialized}
+
+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

@@ -18,37 +18,40 @@ class ScalaExternalLocationProvider(
   externalDocumentation: ExternalDocumentation,
   extension: String,
   kind: DocumentationKind
-)(using ctx: DokkaContext) extends DefaultExternalLocationProvider(externalDocumentation, extension, ctx):
+) extends ExternalLocationProvider:
+  def docURL = externalDocumentation.getDocumentationURL.toString.stripSuffix("/") + "/"
   override def resolve(dri: DRI): String =
     Option(externalDocumentation.getPackageList).map(_.getLocations.asScala.toMap).flatMap(_.get(dri.toString))
       .fold(constructPath(dri))( l => {
-        this.getDocURL + l
+        this.docURL + l
       }
     )
 
   private val originRegex = raw"\[origin:(.*)\]".r
 
-  override def constructPath(dri: DRI): String = kind match {
+  def constructPath(dri: DRI): String = kind match {
     case DocumentationKind.Javadoc => constructPathForJavadoc(dri)
     case DocumentationKind.Scaladoc => constructPathForScaladoc(dri)
     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
-    getDocURL + 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
-    getDocURL + 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
-    getDocURL + location + anchor.fold(extension)(a => s"/$a$extension")
+    docURL + location + extension
   }

scala3doc/src/dotty/dokka/model/api/api.scala

@@ -116,6 +116,7 @@ case class Parameter(
 )
 
 case class TypeParameter(
+  annotations: Seq[Annotation],
   variance: "" | "+" | "-",
   name: String,
   dri: DRI,

scala3doc/src/dotty/dokka/tasty/BasicSupport.scala

@@ -15,15 +15,22 @@ trait BasicSupport:
   export SymOps._
 
   def parseAnnotation(annotTerm: Term): Annotation =
+    import dotty.tools.dotc.ast.Trees.{SeqLiteral}
     val dri = annotTerm.tpe.typeSymbol.dri
+    def inner(t: Term): List[Annotation.AnnotationParameter] = t match {
+        case i: Ident => List(Annotation.LinkParameter(None, i.tpe.typeSymbol.dri, i.name))
+        case Typed(term, tpeTree) => inner(term)
+        case SeqLiteral(args, tpeTree) => args.map(_.asInstanceOf[Term]).flatMap(inner)
+        case Literal(constant) => List(Annotation.PrimitiveParameter(None, constant.show))
+        case NamedArg(name, Literal(constant)) => List(Annotation.PrimitiveParameter(Some(name), constant.show))
+        case x @ Select(qual, name) => List.empty
+        case other => List(Annotation.UnresolvedParameter(None, other.show))
+      }
+
+
     val params = annotTerm match
       case Apply(target, appliedWith) => {
-        appliedWith.flatMap {
-          case Literal(constant) => Some(Annotation.PrimitiveParameter(None, constant.show))
-          case NamedArg(name, Literal(constant)) => Some(Annotation.PrimitiveParameter(Some(name), constant.show))
-          case x @ Select(qual, name) => None
-          case other => Some(Annotation.UnresolvedParameter(None, other.show))
-        }
+        appliedWith.flatMap(inner)
       }
 
     Annotation(dri, params)