forked from scala/scala3
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit 1e637e9
committed
scaladoc: indicate optional parameters with
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
[Cherry-picked d240468][modified]= ...
(scala#23676)1 parent 73a7ac5 commit 1e637e9Copy full SHA for 1e637e9
File tree
Expand file treeCollapse file tree
0 file changed
+0
-0
lines changedFilter options
Expand file treeCollapse file tree
0 file changed
+0
-0
lines changed
0 commit comments