search

scala / scala3

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

API doc: don't separate vals, defs, and objects in different categories #10893

Open smarter opened 3 years ago

smarter commented 3 years ago

Currently, API pages split value members in two categories "Methods" and "Fields", and objects go into the "Type members" categories (even though they're not types), but from the point of view of a user these distinctions do not matter: the way they call and use something does not change based on whether it's an object, val or def, so I suggest grouping all these things as "value members", like Scala 2 does: compare https://www.scala-lang.org/api/current/scala/collection/immutable/TreeSeqMap$.html with http://dotty.epfl.ch/api/scala/collection/immutable/TreeSeqMap$.html

smarter commented 3 years ago

(on the other hand, I think splitting implicit/givens in their own category makes sense since they're used in a different way, I'm not completely sure about whether we should split inherited vs non-inherited (javadoc does it but scaladoc doesn't), but I think that's less important)

abgruszecki commented 3 years ago

I also think that the way that Scaladoc grouped together vals, defs and objects makes sense. It's already there in the new docs. We seem to have a problem though, objects are displayed as vals and their pages can only be accessed by clicking on their type: http://dotty.epfl.ch/api/scala/collection/immutable.html#StringOps

Reg. grouping inherited definitions separately, I think it makes more sense to keep them together by default. The docs of List show that well - most definitions are in a separate group, which doesn't really help with reading them : http://dotty.epfl.ch/api/scala/collection/immutable/List.html . We had plans to allow for dynamic grouping, so perhaps having a toggle that moves inherited definitions to their own group would be good?

/cc @romanowski

pikinier20 commented 2 years ago

I think that currently Scaladoc groups members pretty much like described in this task.

smarter commented 2 years ago

Not completely:

objects go into the "Type members" categories (even though they're not types)

This is not solved.

Also there is a category called "Classlikes" but this term is not standard Scala jargon.