I generally like the reference documentation (https://scala-lang.org/api/3.8.1/docs/index.html).
However, its organization is still done from the point of the Scala 2 migration, which makes them less and less useful as a reference as time goes on. For example:
• extension methods listed under contextual abstractions (just because extensions were simulated with implicit classes in Scala 2)
• type mirrors (type class derivation) also listed under contextual abstraction, not metaprogramming
• a lot of things are just listed under “other new features” or “other changed features”.
I really don’t care any more if things were new or changed, I would like them to be logically organized, so they are easy to find. Maybe also add a grouping based on which Scala version something was added.
Then, many things are also just missing from the reference docs. There is “new control syntax”, but that documents the changes, not the full control syntax. Some of this is kinda available in the book (https://docs.scala-lang.org/scala3/book/control-structures.html), but that is more a “by example” style, not a reference.
It would also be nice if the reference could link to the spec where applicable. Though, the spec has also been “work in progress” for Scala 3 since forever ( Scala Language Specification | Scala 3.4 ).
In some places, the reference docs are pretty close to a specification like text.
For example under ”other new features → Optional Braces ” (not straightforward to find) the text reads pretty much like spec. In fact, the spec links wants to link to that page, but the link in the spec is dead:
page that links: https://scala-lang.org/files/archive/spec/3.4/01-lexical-syntax.html#optional-braces
dead link: https://scala-lang.org/files/archive/spec/3.4/other-new-features/indentation.md
Overall, I think it would be good if the reference docs for Scala 3 would cover all the core language features.
Finally, the macro example repo here: https://github.com/lampepfl/dotty-macro-examples was super helpful to learn more about metaprogramming, would be great to make sure that its highlighted from the docs and remains up to date.