Display tooltips for unresolved links

ScalaCommentToContentConverter needed to be refactored to inherit from
DocTagToContentConverter (because our version of `buildContent` needs to always
be called first before the super version, otherwise nested tags aren't seen by
our implementation).

Author: abgruszecki

scala3doc-testcases/src/tests/tests.scala

@@ -44,10 +44,14 @@ package tests
   *
   * And yet another: [[example.level2.Documentation]].
   *
-  * This is my friend: [[tests\.B\]]].
+  * This is my friend: [[tests.B]].
   *
   * And this is his companion: [[tests.B$ link to the companion]].
   *
+  * And this is a link that failed to resolve [[absent]].
+  *
+  * And this is a link that failed to parse [[#]].
+  *
   * @author Gal Anonim
   * @version 1.0.0
   * @result A class doesn't actually have a result.
@@ -172,7 +176,7 @@ class Methods:
    *
    * Even though this line should be separated from previous one.
    *
-   * @throws scala.Error Throws errors.
+   * @throws java.lang.Error Throws errors.
    * @example
    * ```
    * (m : Methods).generic2(d(), e()): B

scala3doc/src/dotty/dokka/tasty/comments/BaseConverter.scala

@@ -13,7 +13,7 @@ trait BaseConverter {
         val msg = err.getMessage
         // TODO: for better experience we should show source location here
         println("WARN: " + msg)
-        dkkd.A(List(dkk.text(queryStr)).asJava, Map("href" -> "#").asJava)
+        dkkd.A(List(dkk.text(queryStr)).asJava, Map("title" -> msg, "href" -> "#").asJava)
       case Right(query) =>
         thunk(query)
     }

scala3doc/src/dotty/dokka/tasty/comments/MarkdownConverter.scala

@@ -181,7 +181,7 @@ class MarkdownConverter(val repr: Repr) extends BaseConverter {
           dkkd.DocumentationLink(sym.dri, resolveBody(default = targetText), kt.emptyMap)
         case None =>
           println(s"WARN: Definition lookup for following query failed: $queryStr")
-          dkkd.A(resolveBody(default = query.join), Map("href" -> "#").asJava)
+          dkkd.A(resolveBody(default = query.join), Map("title" -> s"Definition was not found: $queryStr", "href" -> "#").asJava)
       }
     }
   }

scala3doc/src/dotty/dokka/transformers/ScalaCommentToContentConverter.scala

@@ -6,25 +6,41 @@ import org.jetbrains.dokka.model.properties.PropertyContainer
 import org.jetbrains.dokka.pages._
 import collection.JavaConverters._
 import org.jetbrains.dokka.base.transformers.pages.comments.{DocTagToContentConverter, CommentsToContentConverter}
+import org.jetbrains.dokka.model.properties.{PropertyContainer, ExtraProperty, ExtraProperty$Key, MergeStrategy}
 import java.util.{Set => JSet, List => JList}
 
+object ScalaCommentToContentConverter extends DocTagToContentConverter {
+  override def buildContent(
+    docTag: DocTag,
+    dci: DCI,
+    sourceSets: JSet[? <: DokkaConfiguration$DokkaSourceSet],
+    styles: JSet[? <: Style],
+    extra: PropertyContainer[ContentNode]
+  ): JList[ContentNode] = docTag match {
+    case docTag: A =>
+      val superRes = super.buildContent(docTag, dci, sourceSets, styles, extra).get(0)
+      val res = superRes.withNewExtras(superRes.getExtra plus ExtraLinkAttributes(
+        title = docTag.getParams.asScala.get("title")
+      ))
+      List(res).asJava
+    case h: Html => List(
+      HtmlContentNode(
+        h.getChildren.asScala.collect{case c: Text => c}.head.getBody,
+        dci,
+        sourceSets.asScala.toSet.toDisplay.asScala.toSet,
+        styles.asScala.toSet
+      )
+    ).asJava
+    case other => super.buildContent(other, dci, sourceSets, styles, extra)
+  }
 
-object ScalaCommentToContentConverter extends CommentsToContentConverter:
-    val defaultConverter = DocTagToContentConverter()
-    override def buildContent(
-        docTag: DocTag,
-        dci: DCI,
-        sourceSets: JSet[? <: DokkaConfiguration$DokkaSourceSet],
-        styles: JSet[? <: Style],
-        extra: PropertyContainer[ContentNode]
-    ): JList[ContentNode] = docTag match {
-        case h: Html => List(
-            HtmlContentNode(
-                h.getChildren.asScala.collect{case c: Text => c}.head.getBody,
-                dci,
-                sourceSets.asScala.toSet.toDisplay.asScala.toSet,
-                styles.asScala.toSet
-            )
-        ).asJava
-        case other => defaultConverter.buildContent(other, dci, sourceSets, styles, extra)
-    }
+  case class ExtraLinkAttributes(title: Option[String]) extends ExtraProperty[ContentNode] {
+    def getKey() = LinkAttributesKey
+  }
+
+  case object LinkAttributesKey extends ExtraProperty.Key[ContentNode, Null] {
+    def mergeStrategyFor(left: Null, right: Null) = MergeStrategy.Fail(
+      () => throw NotImplementedError(s"Property merging for $this is not implemented")
+    ).asInstanceOf[MergeStrategy[ContentNode]]
+  }
+}

scala3doc/src/dotty/renderers/ScalaHtmlRenderer.scala

@@ -158,6 +158,26 @@ class ScalaHtmlRenderer(ctx: DokkaContext) extends SiteRenderer(ctx) {
         ).toString
     }
 
+    override def buildResolvedLink(
+        f: FlowContent,
+        node: ContentResolvedLink,
+        pageContext: ContentPage,
+        sourceSetRestriction: JSet[DisplaySourceSet],
+    ): Unit = {
+        import kotlinx.html.{Gen_consumer_tagsKt => dsl}
+        val c = f.getConsumer
+        val U = kotlin.Unit.INSTANCE
+        dsl.a(c, node.getAddress, /*target*/ null, /*classes*/ null, { e =>
+            import ScalaCommentToContentConverter._
+            // node.getExtra.getMap.asScala.get(LinkAttributesKey)
+            Option(node.get(LinkAttributesKey).asInstanceOf[ExtraLinkAttributes])
+                .flatMap(_.title)
+                .foreach(e.getAttributes.put("title", _))
+            buildText(f, node.getChildren, pageContext, sourceSetRestriction)
+            U
+        })
+    }
+
     override def buildCodeBlock(
         f: FlowContent,
         code: ContentCodeBlock,