Is the more obscure language syntax documented somewhere?

1

I mean things like:
“type t<+'a>” here
or:
“let eval: type a. prim(a) => a = (…)” here

I guess people comming from OCaml would recognise them but for the others is looks like there’s a lot left out of the documentation.

Is it intentional, just lacking behind or am I just missing it?

Thanks

2 Likes
2

It’s intentional. The covariance / contravariance topic is rather complex, while not being too useful for day to day ReScript development, so we wanted to wait before putting it onto the official docs.

Tracking issue can be found here.

2 Likes
3

Let me give a quick explanation (and some concrete examples) of what <+'a> means though:

The + signifies that type 'a is covariant, therefore it is guaranteed that the value 'a will not be mutated.

Example: Js.Promise.t<+'a> states that the wrapped value of a promise is immutable (as soon as a promise resolved with a given value, it will always resolve with the same value).

Also, there’s some implementations of immutable arrays that define a type t<+'a> for their handled values.

This is just a very very simplified description. Maybe someone else can give a more accurate explanation until the full docs land.

3 Likes
4

Thanks Patrick.
It would be nice to at least have these cases linked to OCaml documentation though.
It’s hard to find them for those no familiar with OCaml and google searches on these terms are pretty impossible also.
Does this OCaml documentation parallel exist?

1 Like
5

It’s described here.

1 Like
7

I meant to ask if it would be simple to make a list of rescript undocumented syntax to ocaml documentation.
Then it could be an just obscure part of the rescript documentation containing these links to the “not so obscure anymore” syntax :slight_smile:

8

Current approach is to avoid referencing to ocaml.
As a person who also writes ocaml this is valid to me since rescript is now its own language.
But yeah IMO they should be documented at some point. tho most of the undocumented stuff are the things which are used rarely in day to day development (i.e. unversal qantification, type variance etc.)

9

I don’t get the rational for that decision when the alternative is having existing functionality completely undocumented.
Like me there may be a lot more people starting in ML via javascript and a simple obscure page making these cross references would be great.
But again…I don’t really know what kind of entropy comes with that :wink: