search

scala / bug

Scala 2 bug reports only. Please, no questions — proper bug reports only.
https://scala-lang.org
230 stars 21 forks source link

Missing doc comments for collection operations #12904

Closed odersky closed 6 months ago

odersky commented 7 months ago

Reproduction steps

Looking at

ScalaDoc for ListBuffer

I note that there are quite a few operations that are public but that have no doc comment whatsoever! For instance, dropInPlace, mapInPlace, prependAll.

I consider that a bug. Every collection operation should be documented. This bug is probably worse than a failure of type inference or a compiler crash in obscure cases since it gives a shoddy first impression.

som-snytt commented 7 months ago

This is all mutable API, so it might depend on when you check it.

SethTisue commented 7 months ago

Looks like an oversight that occurred during the 2.13 cycle — the new methods came in through the collection strawman, but then didn't get documented when the straw became flesh.

som-snytt commented 7 months ago

Since I volunteered, I'll reserve the help wanted for when I am desperate. I am adding a scaladoc flag to require doc for public API, to head off regressions. If adding a simple feature to scaladoc 2 were actually simple, the feature would be PR'd already.

While I'm here, my "insight" is that scaladoc should do "outline" checking, to decide which named elements bear doc comments, then use reflection to determine members, extensions, etc. That is similar in concept to scaladoc 2, but it separates "find the doc" from "calculate the class structure to document". (I haven't tried out this concept.)

SethTisue commented 7 months ago

I'll reserve the help wanted for when I am desperate

okay, we can summon the collections crew at PR review time

I am adding a scaladoc flag to require doc for public API, to head off regressions

nice

som-snytt commented 7 months ago

@abebeos this ticket is about API docs.

som-snytt commented 7 months ago

@abebeos I'd suggest commenting on the relevant ticket, where you might mention this ticket as similarly motivating.

Also, I'd suggest that, "Can I talk to a manager?" is not always an effective escalation.

SethTisue commented 7 months ago

@abebeos 1) don't pull Martin in on any random issue that concerns you, it’s really bad manners, and 2) don't intentionally take a ticket off-topic like this

I won't ask again on either point. This is a warning.

Please review https://www.scala-lang.org/conduct/ , and also please use your common sense about what is appropriate behavior in a bug tracker.