Skip to content

Scaladoc permits inheritDoc with different parameter names #12897

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

Closed
som-snytt opened this issue Nov 2, 2023 · 1 comment
Closed

Scaladoc permits inheritDoc with different parameter names #12897

som-snytt opened this issue Nov 2, 2023 · 1 comment
Milestone

Comments

@som-snytt
Copy link

Reproduction steps

Scala version: 2.13.12

getOrElseUpdate is missing defaultValue parameter

compare MapOps

The specific doc problem will be fixed by amending the aberrant signature in MapOps.

Problem

Scaladoc should either complain when inheritDoc but the parameter names do not align, or just fix the doc automagically.

Scala itself doesn't care about parameter names in overrides.

@som-snytt
Copy link
Author

Scaladoc looks for param doc by name, so a renamed parameter does not inherit param doc. (JavaDoc inherits by param position.)

https://www.scala-lang.org/api/2.13.11/scala/collection/mutable/HashMap.html#getOrElseUpdate(key:K,defaultValue:=%3EV):V

Image

The other request is to warn because there might be text referring to the name in the overridden method; but that text could be anywhere, not just in the method description. Enforcing style rules such as "when renaming a parameter, provide doc that explains why the change is meaningful" is not Scaladoc's job.

@som-snytt som-snytt closed this as not planned Won't fix, can't repro, duplicate, stale May 20, 2025
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

2 participants