Every code snippet in the reference docs should compile standalone "within reason"

[ckipp01]

I've been reading through some parts of the reference docs more thoroughly lately since at work we've been doing a Scala 3 series on new features and one thing that has continually come up both as I'm going through the docs and also as I'm helping newcomers to Scala 3 (and sometimes to Scala in general) go through the docs is that there is a ton of implied knowledge in the code examples, especially since the majority of them aren't actually runnable or able to be ran standalone. I strongly believe that pretty much every code snippet in the docs should be able to be ran, or at the very least pasted and ran. I'll give a couple examples of cases that may seem completely obvious to seasoned Scala devs that are used to Scala 3, but could totally trip up newcomers.

Type Class Derivation

The very top example shown here using Tree doesn't compile, because there is no Eq, Ordering, Show. Recently on a workshop we did users assumed they could copy these snippets and get them to work. This is the snippet in question.

enum Tree[T] derives Eq, Ordering, Show:
  case Branch(left: Tree[T], right: Tree[T])
  case Leaf(elem: T)

I think we should be more careful introducing topics without having actual running code or compilable snippets to help better concrete the ideas as people play around with them.

Multiversal Equality

val x = ... // of type T
val y = ... // of type S, but should be T
x == y      // typechecks, will always yield false

Here we introduce the the idea of why Universal equality is dangerous, but we don't actually show a valid code snippet. The user has to infer what x is and what y is. Simple examples like this could be changed to actually show what we mean. For example here are we talking about?

val x = 3
val y = 3.0

x == y

Or are we talking about

val x = 3
val y = "three"

x == y

These example are actually showing something different, but how is a newcomer supposed to really know the difference?

I could continue to find examples of this on almost every page of the reference documentation. Even when we are talking about simple things like significant indentation, the error message we mention don't actually match the compiler is outputing, so if we try them locally, we don't get the same thing. This can be really confusing to newcomers. Take this small example from indentation rules:

if (x < 0) {
  println(1)
  println(2)

println("done")  // error: indented too far to the left

What is the code snippet supposed to actually be showing? The writing seems to make you think the example is supposed to illustrate how the compiler will warn you that something is too far left, but if you run this snippet you get:

-- [E103] Syntax Error: /Users/ckipp/Documents/scratch-workspace/indent.scala:1:0
1 |if (x < 0) {
  |^^
  |Illegal start of toplevel definition
  |
  | longer explanation available when compiling with `-explain`
1 error found
Errors encountered during compilation

Well maybe that's because it's really a script and not a Scala file (fair enough):

Compiling project (Scala 3.2.2, JVM)
[error] ./indent.sc:26:1: '}' expected, but eof found
[error] ./indent.sc:1:17: Not found: x
[error] if (x < 0) {
[error]                 ^
[warn] ./indent.sc:5:1: Line is indented too far to the left, or a `}` is missing
[warn] println("done")  // error: indented too far to the left
[warn] ^
[warn] ./indent.sc:7:1: Line is indented too far to the left, or a `}` is missing

Now we finally see the warning (not an error) and instead we see a much bigger error about the x not being found which takes the focus away from what the example is supposed to illustrating.

As a rule of thumb, I think in this day and age with the tools we have available to us, there is no reason not to have either code snippets that are runnable or code snippets that have been typechecked using something like mdoc.