Probably there is a design discussion somewhere, but just yesterday I was appreciating the obvious strike-thru to indicate deprecation in Scaladoc 2. I would actually prefer the international symbol 🔴 I mean the red circle with strike-thru, here is the emoji via twitter:

Plus the message, of course.

Scala 2 does show the deprecation message:

there is code in MemberRenderer.scala that appears to attempt to implement this!

    val message = named.find(_.name.get == "message")
    val since = named.find(_.name.get == "since")
    ...

we'll have to figure out why it doesn't work

Ahh, so @HarrisL2 figured out that it sometimes does work! it works if the deprecation was done with named arguments, like this:

@deprecated(message = "foo", since = "2.10.0")

but it doesn't work if the names on the named arguments are missing:

@deprecated("foo", "2.10.0")

We don't know if it's safe to just access the parameters by position, but we don't seem to have any choice. We'll need to make sure it still works if the order at the call site is swapped, like @deprecated(since = "2.10.0", message = "foo")

If it doesn't work when the order is swapped, then we'll need to use the names if they are present, and only fall back to positional if we must.

We never finished figuring out the correct way to add a unit test for this. We'll need to figure that out before we un-draft the PR. Do we need to write a JSoup-based test?

The testing methodology I used instead was to publishLocal a modified compiler, then use scala-cli to run it on a test source file with scala doc -S 3.6.3-RC1-bin-SNAPSHOT .

The test source file:

class C:
  /** one */
  @deprecated("without names", "2.10.0")
  def foo = 0
  /** two */
  @deprecated(message = "with names", since = "2.10.0")
  def bar = 1
  /** three */
  @deprecated(since = "2.10.0", message = "backwards names")
  def baz = 2

the code change:

--- scaladoc/src/dotty/tools/scaladoc/renderers/MemberRenderer.scala
+++ scaladoc/src/dotty/tools/scaladoc/renderers/MemberRenderer.scala
-    val (named, unnamed) = a.params.partition(_.name.nonEmpty)
-    val message = named.find(_.name.get == "message")
-    val since = named.find(_.name.get == "since")
+    val message = a.params.lift(0)
+    val since = a.params.lift(1)

rendered:

It seems that the existing test suite only tests for the generated signatures, and does not concern with annotations. We will have to add a new test type to test for the deprecated annotation.