Prelude for examples?

[fhammerschmidt]

The examples all work and pass the tests again, but there is some boilerplate in many of them.

Especially the

module IntCmp =
  Belt.Id.MakeComparable({
    type t = int;
    let cmp = Pervasives.compare;
  });

in Set or Map examples makes the whole thing harder to read. What if we had some prelude which gets copied implicitly to every example where it is needed?

The examples could have 2 viewing modes:

• a concise one
• a complete one

[nikgraf]

Makes sense to me. Not sure though if it's worth all the engineering & maintenance effort this will bring. I think the bigger value at this point is making more examples or documenting the Js space.

@ryyppy thoughts?

[fhammerschmidt]

Yeah, surely this is not the highest priority. Just to keep it in mind.

[ryyppy]

If it's really taking over, I can imagine adding some kind of prelude.js file, which allows injecting prelude code in each code snippet (either spaced to a specific module, or easier, for all modules).

There's some things to watch out for, like in case of an error, we need to account the line numbers of the injected code sample and correct the reported line number in the error message.

Let's get back to this if we have more data on how unreadable examples get before doing this.

[ryyppy]

Another idea would be to have an export prelude = "my code" in the mdx file (probably better, since we can scope each prelude to the module itself and it's easier to author it)

Actually the simplest way is introducing a re prelude codeblock. See PR.