Skip to content

Hide @deprecatedName in Scaladoc #13117

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cayhorstmann opened this issue Jul 20, 2021 · 4 comments
Open

Hide @deprecatedName in Scaladoc #13117

cayhorstmann opened this issue Jul 20, 2021 · 4 comments

Comments

@cayhorstmann
Copy link

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 #13116

@Kordyjan
Copy link
Contributor

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
Copy link
Author

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

@BarkingBad
Copy link
Contributor

Possible duplicate of #11136 and #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
Copy link
Contributor

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.
#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".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants