search

scala / scala3

The Scala 3 compiler, also known as Dotty.
https://dotty.epfl.ch
Apache License 2.0
5.88k stars 1.06k forks source link

Hide @deprecatedName in Scaladoc #13117

Open cayhorstmann opened 3 years ago

cayhorstmann commented 3 years ago

Consider 

 def exists(@deprecatedName("f", "2.13.3") p: A => Boolean): Boolean

in http://dotty.epfl.ch/api/scala/collection/ArrayOps.html#exists-fffff66f. For 99.99% of the users, the fact that p used to be f is irrelevant, yet it takes up almost 50% of the visible space. It could be completely suppressed, or represented as a ... that, when clicked reveals the full content, or revealed when one mouses over the suitably higlighted p. See also https://github.com/lampepfl/dotty/issues/13116

Kordyjan commented 3 years ago

Definitely, it should be filtered out from the signature. I don't have an opinion if it should be mentioned in the full description or if it is just irrelevant detail that can be skipped entirely.

cayhorstmann commented 3 years ago

Another thing worth hiding is @SerialVersionUID, see e.g. http://dotty.epfl.ch/api/scala/util/matching/Regex.html

BarkingBad commented 3 years ago

Possible duplicate of https://github.com/lampepfl/dotty/issues/11136 and https://github.com/lampepfl/dotty/issues/11120

I proposed to introduce meta-annotation @MustBeDocumented as in Java and Kotlin so we would not have to decide on our own about which annotations are relevant to API docs and which are not, yet it didn't receive much support.

Nonetheless, in my opinion, expanding on hover can be unintuitive, and would be tremendous/impossible to look at the whole signature when there would be two or three annotations. How about expanding the whole signature when there is an expanded tab, and hiding annotations when the tab is collapsed, e. g.: (Actually we have such feature for class annotations when listed in tabs, so I think it's bug/misimplementation that infix annotations for method parameters don't hide)

obraz obraz

For main pages of classes/objects/traits etc. I can make the signature frame collapsable too, so the annotations would be hidden until expanded. (e. g. SerialVersionUID)

How do you find proposed changes?

som-snytt commented 11 months ago

dotc ignores deprecatedName and it seems dottydoc does too, or do I miss it?

A related issue is how to present when param names change in overrides. https://github.com/lampepfl/dotty/issues/18831 It would be amazing if doc were rendered "as viewed from" a particular signature, in a class or "at a previous (deprecated) version". A drop-down could offer "as seen from class C" or "as seen at version 2.13".