Scala documentation, web sites: What should be improved?

[SethTisue]

Context

This thread is for a project covered by Sovereign Tech Fund’s investment in Scala.

For the full context, please read the announcement blog post: The Sovereign Tech Fund invests in Scala | The Scala Programming Language

On this forum, each project supported through this investment has its own dedicated thread.

This thread covers Work Package F: API Documentation and will be used to share the project overview, a roadmap with key milestones, ongoing progress updates, and opportunities to engage—so we can hear ideas from the community and encourage contributions.

What we want to hear from you

Please tell us your ideas for improving any of Scala’s documentation. Let us know what is:

• Outdated
• Incomplete or poor quality
• Missing entirely

And let us know what improvements would be most helpful to both:

• New users coming to Scala
• Existing users of Scala

We’re interested both in specific suggestions (e.g. “stdlib class X has almost no Scaladoc”) and also in more general feedback on the state of Scala documentation. Specific suggestions are more easily actionable, but general suggestions have a chance at spurring action, too.

What’s in scope?

The work package is named “API Documentation”, and a major focus will be on the Scaladoc for the standard library. But the overall scope also includes the documentation on our website such as the Scala language specification, getting-started docs, language tour, features guides, Scala Toolkit documentation, and so forth.

Improving existing documentation is in scope. Adding entirely new documentation is also in scope. (Identifying and removing grievously outdated documentation is fair game, too.)

If limitations of the Scala 3 Scaladoc tool are causing quality issues in the doc, improving the tool is in scope.

We are primarily interested in improving Scala 3’s documentation, but we could also make some improvements on the Scala 2 side.

What’s not in scope?

Third-party tools, libraries, and publications are not in scope.

Regardless, it is sometimes appropriate for us to link to third-party documentation from the Scala website, and that’s a potential area of improvement.

Examples of our documentation on third-party resources include the Scala community page, the Scala IDEs page, the Scala Toolkit documentation (because the Toolkit includes third-party libraries), and the Scala books page. Improving pages such as these is in scope.

Then what happens?

We’ll collect and assess all of the suggestions.

We’ll choose some items to work on ourselves. We’ll use this thread to report on our progress from time to time, and to invite volunteers to review pull requests.

We may promote some other items as especially ripe for volunteers to tackle, in the hopes that volunteers will step forward.

Who’s involved?

Scala Center team members on this project are: Seth Tisue (team lead), Bill Venners, Chua Chee Seng, Guillaume Martres. Others might get involved later.

[kubukoz]

Hi!

Small thing, but some documentation pages for Scala 3 features (that went from experimental to stable), contains dead links. For example: if you Google for “named tuples scala”, you get Named Tuples as the second link. It’s valid, but the link “Click here to find the stable version of this page.” is not - it should be Named Tuples .

Perhaps there are more cases like this.

[Sporarum]

Something which I found lacking is ways to go from beginner pages to more in-depth ones
For example the page on partial functions does not link to anything !
Neither to the stdlib definition nor to the spec of pattern matching anonymous functions

And more generally where to find information is sometimes inconsistent
For example I was not able to find a page about enums in the Scala book, but there are two pages in the reference (the first does link to the second however), and a page in the stdlib

I remember having a lot of trouble finding the stdlib docs (for Scala 3 for sure, for Scala 2 maybe as well) until I learned to add api to my search
(It is a simple trick, but I would not expect beginners to stumble upon it)

Overall, I feel everything I use (and see used, for example in users) is properly documented somewhere for both beginners and experts, but those are usually harder to find than they need to be.

[AMatveev]

May be it is possible to reduce barrier to entry which is needed to make merge requests. Some ideas:

• to recommend vs code previewer which allows to write documentation without needing to install and learn documentation build tool(see analog).
• to assign a technical writer to help fix typographical errors in incoming merge requests. Typographical bugs can be fixed by the technical writer without need to discuss.

At least we have come to this in our company.

[Sporarum]

Oh yes, I did find something is missing, details on SAM-conversions !

The best official documentation I have found is in the Scala 2.12 release notes which is not ideal
(and I didn’t even find this myself, only through a stack overflow answer)

Ideally the documentation should not assume knowledge of Java’s SAM-conversions
(And this is valid more broadly)

If added it would allow us to link to it from the pages that refer to the concept, see for example “SAM class” mentioned here

[JD557]

Nitpick, but can we get a UI/UX designer to work on the Scaladoc style.

Not that I think it’s ugly, and I’m not the best person to comment on this, but I believe it might have some issues.

One is the lack of colors in text heavy pages: It’s just a mix of grays and blacks, so things like links and monospace text (I’m not talking about code snippets) don’t really pop out, making the text a bit hard to follow…
Maybe having some indicator near external links could also help.

Another is the left-side pane… There’s just so much irrelevant information there…
Maybe a localized search bar or some different grouping strategy would help?

Compare this with MDN:

Text is colorful, external links are correctly pointed out, implementation references are collapsed (similar to packages) but are automatically expanded when you use the filter function.

[bishabosha]

@kubukoz

you get Named Tuples as the second link. It’s valid, but the link “Click here to find the stable version of this page.” is not - it should be Named Tuples .

Already it’s a problem that the “nightly” banner appears in the first place

[WojciechMazur]

That’s an issue of most docs published between Scala 3.4-3.6, fixed just recently in the 3.7 series - we might need to regenerate and update the old docs to get rid of these.

The reference docs were designed to keep stable links, these however were incorrectly maintained for some time, and issues related to links stability were discarded. We’ve improved it regarding the latest release but stable pages regarding named tuples must have been lost in the past.
I’ve pushed changes adding missing stable pages for experimental/named-tuples and some other pages - these should be soon available.

I have some ideas how to improve stability and ux of reference pages, and would try to work on these, although it work require some fixes in the Scaladoc.

[jducoeur]

Personal opinion: it would be helpful for code examples to show in both the “old” and “new” coding styles. Newer folks tend to be all-in on the braceless style, but for those of us with big legacy codebases, who want to nudge people towards Scala 3, it’s a speedbump for reading comprehension.

[ragnar]

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.

[AMatveev]

There is absence of navigation between types and its extensions in scala doc.

We actualy have to use text search to see available methods in TypeRepr.

It is quite uncomfortable.

[charpov]

I regularly end up looking at classes with zero documentation. Often (but not always), they are used for implicit conversions (e.g., classes that appear in the Numeric, Ordering or ArraySeq companion objects, or if you somehow land up on Priority0FunctionExtensions). It’s unfortunate that these classes need to be public and I wish there were a way to hide them from the documentation. They can create a lot of noise, especially for beginners.

[rssh]

I can’t find a list of Scala 3 compiler options. I think that this should be one-click, but it’s not.

(I have trying to create one, but the problem is that the current list of options is a migration guide, and to have a separate page means find place for it, which means reorganizations, which is out of my control)

[kitbellew]

In addition to other ideas relating to organization and discoverability, I’d like to suggest that documentation would be firmly in sync with reality, and every feature ideally mentioned along with the version(s) of scala it appeared in.

The only document I recall which mentioned specific versions is Wildcard Arguments in Types, and yet I think either the versions evolved with time (if the current state is accurate), or they were describing a plan at some point but one which didn’t pan out and wasn’t updated.

Here’s another example: this document Macros Spec describes “quoted identifiers” as something that is part of the language, just like quoted blocks just below. And yet no known version of scala supports these, instead continuing to complain about “symbol literals”.

If the documentation is at odds with reality, people might learn not to rely on it, making it not as useful.

[som-snytt]

scala-cli tries to --help and this UI seems to collapse hyphen-hyphen to em dash even in backticks, but it takes me a few tries to recall it.

  --scalac-help, --help-scalac               Show help for scalac. This is an alias for --scalac-option -help

I’d prefer if it showed me all the options at once, -W -X -Y instead of making me beg for it.

I wouldn’t mind if it spawned a browser and served it in a page.

While we’re at it, a doc command that does the same for Scaladoc pages.

–help just to confirm for my personal well-being that it does rewrite to em dash when you enter it. I edited it above.

[som-snytt]

Are you saying this example code should not compile?

def power2(x: Double): Double =
  ${ unrolledPowerCode('x, 2) } // x * x

It also has a suspicious example

'{
  val x = ...
  ${ unrolledPowerCode('{x}, 3) } // evaluates to: x * x * x
}

The quoted ident works in a local example.

Sorry in advance if I missed the point.

[kitbellew]

Using the spec, I added a scalafmt rewrite which drops {} for quoted identifiers. As a result, scalameta code base wouldn’t build under 3.3.7.

Another data point is RedundantBraces in 3.10.5 removes necessary braces in quoted macros · Issue #5202 · scalameta/scalafmt · GitHub ; the author claims the compiler complains in 3.8.1 as well.

So, what’s the rule? When is ’foo OK? While I am very interested in learning the truth to solve the immediate problem, for the context of this topic it’s important that there seems to be ambiguity, and the documentation doesn’t clarify it.

[datalin]

I would really appreciate thorough documentation and guides on metaprogramming and macros with helpful examples. Information is currently scattered across talks and blog posts.

[markehammons]

I recently learned that the scaladoc for scala 3 isn’t really viewable without either going to the website, or booting a webserver that serves the docs to your browser. It could be nice if scala/scala-cli had an option to autoboot a webserver with the docs you want to view, in the case you have the docs pre downloaded (I think the javadoc jars), but have no internet access or don’t want to waste bandwidth querying the scala website.

[charpov]

@markehammons

I recently learned that the scaladoc for scala 3 isn’t really viewable without either going to the website, or booting a webserver that serves the docs to your browser.

Interestingly enough, I had the same problem with Scaladoc-generated documentation for class assignments. I used to have to display docs via a Python server. However, the problem suddenly went away about 6 months ago and I can now open index.html with a browser. I’m sure I don’t get all the functionalities (i.e., type-aware searches), but it’s usable. I wonder if something has changed within Scaladoc.