Scaladoc fails to re-substitute macros for inherited members

[Lasering]

Minimized code

/** @define macro Super */
abstract class Super {
  /** $macro */
  def inherited: Int = 5
  /** $macro */
  def implemented: Unit
  /** $macro */
  def overridden: String = "test"
}
/**
 * @define name default
 * @define dummy dummy
 */
trait A[T] {
  /** List $name */
  def list(): List[T]
  /** Gets the $name with the given $dummy */
  def get(id: String): Option[T] = None
}
/** @define dummy id */
trait B extends A[String]
/**
 * @define macro Sub
 * @define name banana
 */
class Sub extends Super with B {
  def list(): List[String] = List.empty
  def implemented: Unit = ()
  override def overridden: String = "overridden test"
}

build.sbt

name := "scala-doc-tests"
version := "0.1.0"
scalaVersion := "3.0.0-M2"

Run:

mkdir docs
sbt doc

Expectation

The resulting documentation has the same problems as described scala/bug#9785.

[abgruszecki]

@Lasering the issue report is really helpful, thanks for raising it and attaching all of the details!

I've noticed that, much like the original bug in Scaladoc, this one is a good introduction to compiler internals (and, by extension, Tasty Reflect). The basic problem is that we key expanded docstrings with the symbol they were attached to, but what we should be doing instead is keying them with the symbol they were attached to, and their expansion site. If someone is looking to "get their feet wet" with compiler internals, this issue isn't a bad one to start with.

[Lasering]

I've already solved the problem in Scala2: https://github.com/scala/scala/pull/9060/files. But from your explanation seems the cause is different in Scala3. I can try to solve it.

Not sure if its even possible, but this idea of defining variables in the docs could be made to work across jar boundaries? Let me give a more detailed explanation:

1. In package com.project.common create trait A whose scaladoc is something like /** @define model model */.
2. Release the classes in that package to maven central to an artifact say: "com.project" %% "project-common" % "0.1.0"
3. Create a project which has as a dependency the above artifact.
4. In package com.project.service create class MyService which extends A and whose scaladoc is /** @define model MyService */
5. Generate the docs of this new project.
6. The docs for class MyService should have the string MyService interpolated in the original methods of A instead of the string model (which is what happens currently).

[abgruszecki]

@Lasering with our approach, what you outlined is indeed possible (or at least I'd be deeply surprised if it wasn't). Scala3doc doesn't create dependencies based on source files, it instead loads .tasty files created by the Scala3 compiler (and published on Maven). This means that from our perspective, there's 0 difference between definitions of the current project, and definitions of other projects.

[smarter]

Before going further, please check that the problem is reproducible with Scala 3.0.0-M3 and sbt-dotty 0.5.0 since dottydoc was replaced by scala3doc in that release.

[Lasering]

With those versions there are some improvements, but there are still misses:

• abstract class Super every scaladoc is correct
• trait A every scaladoc is correct
• trait B method get has incorrect scaladoc: Gets the default with the given dummy, should be Gets the default with the given id. Method list also has incorrect scaladoc if trait B defines name in scaladoc.
• class Sub has every scaladoc wrong. The methods inherited and get have incorrect interpolations. Methods list, implemented, overriden didn't even inherited the scaladocs (see image https://imgur.com/iGdSzHI)

[Lasering]

we key expanded docstrings with the symbol they were attached to

@abgruszecki can you point me to where this is being done?

[abgruszecki]

This is the entrypoint to "comment cooking": https://github.com/lampepfl/dotty/blob/master/scala3doc/src/dotty/dokka/tasty/comments/CommentExpander.scala#L345
and this is the method that actually "keys" (caches, I guess) expanded docstrings: https://github.com/lampepfl/dotty/blob/master/compiler/src/dotty/tools/dotc/core/Comments.scala#L34
README in scala3doc should give you some pointers for actually testing your work: https://github.com/lampepfl/dotty/blob/master/scala3doc/README.md#L1