scaladoc: indicate optional parameters with = ... (scala#23676)

currently, there is no indication in the scaladoc when parameters may be
optional. this leads to [long and overwhelming signatures][1] which is
not at all user-friendly. users are forced to first intuit that this
method *might* have some optional parameters, then manually find [the
source code][2] to learn which parameters are optional.

[1]:
https://javadoc.io/static/com.lihaoyi/os-lib_3/0.11.5/os/proc.html#call-fffff910
[2]:
https://github.com/com-lihaoyi/os-lib/blob/0.11.5/os/src/ProcessOps.scala#L192-L205

this PR suffixes `= ...` after the type signature of optional
parameters. this makes it possible to tell that these parameters are
optional and may be omitted.

this applies to both method parameters and class parameters. the format
is intentionally similar to the definition of such optional parameters
in code:
```scala
// new scaladoc display:
def f(x: Int, s: String = ...): Nothing

// code:
def f(x: Int, s: String = "a"): Nothing
```
of course, the `...` term is different. i think this is a reasonable
choice because (1) ellipsis commonly represents something present but
omitted, and (2) it is not valid Scala, so there is no risk someone will
think this is denoting a literal default value of `...`. a proper
ellipsis character (rather than 3 periods) could also be considered, but
i found that looked out of place amongst the monospace signature.

about displaying the default value itself, this PR does not display the
default value. this is because of anticipated difficulties around
displaying an expression. this could be re-visited in future, but i
think it should not hold up this PR. i believe that this PR alone is
already a substantial improvement for the documentation of optional
parameters.

finally, here is a screenshot of the scaladoc from the new
optionalParams.scala test case:
<img width="663" height="646" alt="image"
src="https://github.com/user-attachments/assets/870410ee-0535-484b-84c8-8b683464471e"
/>

this might be related to scala#13424

Author: katrinafyi

scaladoc-testcases/src/tests/extendsCall.scala

@@ -3,4 +3,4 @@ package extendsCall
 
 class Impl() extends Base(Seq.empty, c = "-") //expected: class Impl() extends Base
 
-class Base(val a: Seq[String], val b: String = "", val c: String = "") //expected: class Base(val a: Seq[String], val b: String, val c: String)
+class Base(val a: Seq[String], val b: String = "", val c: String = "") //expected: class Base(val a: Seq[String], val b: String = ..., val c: String = ...)

scaladoc-testcases/src/tests/optionalParams.scala

@@ -0,0 +1,23 @@
+package tests
+package optionalParams
+
+class C(val a: Seq[String], val b: String = "", var c: String = "") //expected: class C(val a: Seq[String], val b: String = ..., var c: String = ...)
+{
+  def m(x: Int, s: String = "a"): Nothing //expected: def m(x: Int, s: String = ...): Nothing
+    = ???
+}
+
+def f(x: Int, s: String = "a"): Nothing //expected: def f(x: Int, s: String = ...): Nothing
+  = ???
+
+extension (y: Int)
+  def ext(x: Int = 0): Int //expected: def ext(x: Int = ...): Int
+    = 0
+
+def byname(s: => String = "a"): Int //expected: def byname(s: => String = ...): Int
+  = 0
+
+enum E(val x: Int = 0) //expected: enum E(val x: Int = ...)
+{
+  case E1(y: Int = 10) extends E(y) //expected: final case class E1(y: Int = ...) extends E
+}

scaladoc/src/dotty/tools/scaladoc/tasty/ClassLikeSupport.scala

@@ -443,12 +443,13 @@ trait ClassLikeSupport:
     val inlinePrefix = if argument.symbol.flags.is(Flags.Inline) then "inline " else ""
     val nameIfNotSynthetic = Option.when(!argument.symbol.flags.is(Flags.Synthetic))(argument.symbol.normalizedName)
     val name = argument.symbol.normalizedName
+    val defaultValue = Option.when(argument.symbol.flags.is(Flags.HasDefault))(Plain(" = ..."))
     api.TermParameter(
       argument.symbol.getAnnotations(),
       inlinePrefix + prefix(argument.symbol),
       nameIfNotSynthetic,
       argument.symbol.dri,
-      memberInfo.get(name).fold(argument.tpt.asSignature(classDef))(_.asSignature(classDef)),
+      memberInfo.get(name).fold(argument.tpt.asSignature(classDef))(_.asSignature(classDef)) :++ defaultValue,
       isExtendedSymbol,
       isGrouped
     )

scaladoc/src/dotty/tools/scaladoc/tasty/TypesSupport.scala

@@ -233,7 +233,7 @@ trait TypesSupport:
             tpe(tp.typeSymbol)
           case _: TermRef | _: ParamRef =>
             val suffix = if tp.typeSymbol == Symbol.noSymbol then tpe(typeName).l else tpe(tp.typeSymbol)
-            inner(qual)(using skipTypeSuffix = true) ++ plain(".").l ++ suffix
+            inner(qual)(using indent = indent, skipTypeSuffix = true) ++ plain(".").l ++ suffix
           case ThisType(tr) =>
             findSupertype(elideThis, tr.typeSymbol) match
               case Some((sym, AppliedType(tr2, args))) =>
@@ -250,7 +250,7 @@ trait TypesSupport:
                 val sig = inParens(inner(qual)(using indent = indent, skipTypeSuffix = true), wrapping)
                 sig ++ plain(".").l ++ tpe(tp.typeSymbol)
           case _ =>
-            val sig = inParens(inner(qual, skipThisTypePrefix), wrapping)
+            val sig = inParens(inner(qual), wrapping)
             sig ++ keyword("#").l ++ tpe(tp.typeSymbol)
         }
 

scaladoc/test/dotty/tools/scaladoc/signatures/TranslatableSignaturesTestCases.scala

@@ -124,3 +124,5 @@ class InfixTypes extends SignatureTest("infixTypes", SignatureTest.all)
 class ExtendsCall extends SignatureTest("extendsCall", SignatureTest.all)
 
 class RightAssocExtension extends SignatureTest("rightAssocExtension", SignatureTest.all)
+
+class OptionalParams extends SignatureTest("optionalParams", SignatureTest.all)