Scala3doc: cook comments

Resolve @define-s and expand @inheritdoc-s.

Author: abgruszecki

compiler/src/dotty/tools/dotc/core/Comments.scala

@@ -44,7 +44,13 @@ object Comments {
    * @param expanded If this comment has been expanded, it's expansion, otherwise `None`.
    * @param usecases The usecases for this comment.
    */
-  final case class Comment(span: Span, raw: String, expanded: Option[String], usecases: List[UseCase]) {
+  final case class Comment(
+    span: Span,
+    raw: String,
+    expanded: Option[String],
+    usecases: List[UseCase],
+    variables: Map[String, String],
+  ) {
 
     /** Has this comment been cooked or expanded? */
     def isExpanded: Boolean = expanded.isDefined
@@ -65,7 +71,7 @@ object Comments {
     def expand(f: String => String)(using Context): Comment = {
       val expandedComment = f(raw)
       val useCases = Comment.parseUsecases(expandedComment, span)
-      Comment(span, raw, Some(expandedComment), useCases)
+      Comment(span, raw, Some(expandedComment), useCases, Map.empty)
     }
   }
 
@@ -74,7 +80,7 @@ object Comments {
     def isDocComment(comment: String): Boolean = comment.startsWith("/**")
 
     def apply(span: Span, raw: String): Comment =
-      Comment(span, raw, None, Nil)
+      Comment(span, raw, None, Nil, Map.empty)
 
     private def parseUsecases(expandedComment: String, span: Span)(using Context): List[UseCase] =
       if (!isDocComment(expandedComment))

scala3doc-testcases/src/tests/tests.scala

@@ -10,6 +10,8 @@ package tests
   * This is an *important* _test_ class.
   * Important enough to get multiple sentences in its summary.
   *
+  * Here is foo: $foo
+  *
   * And `this` is inline code.
   *
   * And this is the **strong** __emphasis__ test.
@@ -56,17 +58,25 @@ package tests
   * @version 1.0.0
   * @result A class doesn't actually have a result.
   * @constructor A class has a constructor, and this one is important.
+  *
+  * @define foo Foo expanded.
   */
 class A {
 
-  /** This is a method.
+  /** This is my method.
     *
     * This is a link: [[AA]].
     *
     * This is another link: [[AA$]].
     *
     * And yet another: [[B]].
     */
+  final def myMethod(s: String): String = s
+
+  /** This is a method.
+    *
+    * This is foo: $foo
+    */
   def method(s: String): String = s
 
   class AA
@@ -85,6 +95,8 @@ object A
   *
   * This is an ''important'' '''test''' __class__. And `this` is inline code.
   *
+  * Here is foo: $foo
+  *
   * While
   * {{{
   * this.is("a code block")
@@ -104,9 +116,15 @@ object A
   *
   * And this is his companion: [[tests.A$]].
   * @syntax wiki
+  * @define foo Bar, actually.
   */
 class B extends A {
-  /** This is a method. */
+  /** @inheritdoc */ override def method(s: String): String = s
+
+  /** This is a method.
+    *
+    * And this is my foo: $foo
+    */
   def otherMethod(s: String): String = s
 
   class BB

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

@@ -12,11 +12,27 @@ trait ScaladocSupport { self: TastyParser =>
   import qctx.reflect._
 
   def parseComment(
-    commentNode: Documentation,
+    commentPre: Documentation,
     tree: Tree
   ): dkkd.DocumentationNode = {
+    val commentNode =
+      if tree.symbol.isClassDef || tree.symbol.owner.isClassDef then
+        import dotty.tools.dotc
+        given ctx as dotc.core.Contexts.Context = qctx.asInstanceOf[scala.quoted.runtime.impl.QuotesImpl].ctx
+
+        // println(s"Expanding comment for sym: ${tree.symbol.show}")
+        val sym = tree.symbol.asInstanceOf[dotc.core.Symbols.Symbol]
+        val owner =
+          if tree.symbol.isClassDef then sym else sym.owner
+
+        comments.CommentExpander.cookComment(sym, owner)(using ctx)
+          .get.asInstanceOf[Documentation]
+      else
+        commentPre
+
+    val commentString = commentNode.expanded getOrElse commentNode.raw
     val preparsed =
-      comments.Preparser.preparse(comments.Cleaner.clean(commentNode.raw))
+      comments.Preparser.preparse(comments.Cleaner.clean(commentString))
 
     val commentSyntax =
       preparsed.syntax.headOption match {