Extensible variants are undocumented

[bobzhang]

transferred from rescript-lang/rescript#4869 by @earksiinni

I encountered the following code in the wild:

type thunk('state) = ..;

type ReduxThunk.thunk(_) +=
  | StringAction (stringAction)
  | CounterAction (action);

This code essentially creates an "extensible variant" called thunk and adds two constructors to it. I'm not certain whether I'm using the right term to explain this feature since it's not described anywhere in the ReasonML or ReScript docs. It should be.

The ReScript docs also don't explain .., which is an elision, which is documented in ReasonML's docs on open objects. ReScript's docs don't talk about open objects at all, let alone elisions, but both sets of docs omit the fact that you can apparently use elisions to define extensible variants.

The use of the += feature isn't described anywhere in either set of docs, either.

It would be great to describe all these features, and while we're at it it would be great to have ReScript docs on polymorphic variants and how they differ from this kind of extensible non-polymorphic variant.

[ersinakinci]

Btw, @yawaramin helpfully explained to me that extensible variants are an OCaml feature: https://caml.inria.fr/pub/docs/manual-ocaml/extensiblevariants.html. I just messed around with syntax until I figured it out and apparently reinvented the same name :-)

[ryyppy]

The ReScript docs also don't explain .., which is an elision, which is documented in ReasonML's docs on open objects. ReScript's docs don't talk about open objects at all, let alone elisions, but both sets of docs omit the fact that you can apparently use elisions to define extensible variants.

Yeah, we don't support the OCaml Object features, that's why there is no open object docs. I personally never used extensible variants, so I thought they were not included in the current ReScript syntax.

We can add an extra title in the Variants section to explain extensible variant syntax, and we should probably add it to the syntax discovery widget as well.