Scaladoc is inherited with different parameter names

[som-snytt]

Compiler version

3.3

Minimized code

mutable.HashMap#getOrElseUpdate renames parameter ops to defaultValue, but inheritDoc does not warn or adjust.

Output

Dottydoc improves on Scaladoc 2, which simply omits the spurious param.

Expectation

It would be nice to get a warning (I didn't actually check whether Dottydoc warns) or fix up the name @param name. (References in the doc text would require edits.)

Scaladoc 2 also does not cope.

[som-snytt]

More generally, dottydoc does not check the @param name. Noticed when I @deprecatedName: I fixed the compilation error with the new name, but there was no doc warning or error. (It would be fine to support correlating a deprecated name.)

[som-snytt]

If anyone is thinking of fixing this (and if it's still an issue), the original symptom was fixed in mutable.Map by

 def getOrElseUpdate(key: K, @deprecatedName("op", since="2.13.13") defaultValue: => V): V

The original observation was that @inheritdoc will use text in which I may have "hardcoded" a parameter name. JavaDoc just says be careful:

If parameter names differ, care should be taken when inheriting such parameter documentation...

The actual bug is showing the wrong name for a parameter. JavaDoc shows the current name and:

the corresponding part of the overridden method documentation is matched using the parameter's position, not the parameter's name

https://docs.oracle.com/en/java/javase/24/docs/specs/javadoc/doc-comment-spec.html

In Scaladoc, elements are not automatically inherited if there is any doc, and @inheritdoc means use the text, not tags such as @return. So the only problematic case is F below.

package p

class C {
  /** Sums the numbers.
   *
   *  @param i one number
   *  @param j another number
   *  @return the sum of them
   */
  def sum(i: Int, j: Int) = i + j
}

class D extends C {
  /** @inheritdoc
   *  @example just call sum
   */
  override def sum(x: Int, y: Int) = (x + y) * 2
}

class E extends C {
  /**
   *  @example just call sum
   */
  override def sum(x: Int, y: Int) = (x + y) * 2
}

// missing doc results in inherited param elements with wrong names
class F extends C {
  override def sum(x: Int, y: Int) = (x + y) * 2
}

class G extends C {
  /** More words.
   */
  override def sum(x: Int, y: Int) = (x + y) * 2
}