Convert belt comment doc examples to rescript syntax

[amiralies]

They are currently written in ml syntax.
Another approach would be converting them in rescript-editor-support's dump command (since main use case is hover IMO).
I think we eventually need to convert belt itself to rescript syntax. examples can be converted at that moment too, what do you think?

Edit: Screenshot (this is so weired for newcomers to see ml examples)

[bobzhang]

cc @ryyppy
In the short term, we can do the conversion on the fly
In the long term, we should switch to the rescript syntax ( there may be issues with ocaml stdlib)

[ryyppy]

Not sure how hard it would be to parse examples from the strings to convert them on the fly. We wanted to add the rescript syntax to the editor-support to be able to do proper parsing / printing of signatures.. so this might be the first step to do on the fly conversion?

[amiralies]

Did an experiment using res_multi_printer of rescript-syntax

For using this we need to vendor the whole syntax repo (in order to parse ML and convert them to Res).
Currently we only use a subset of syntax repo for printing types (outcome printer)

[ryyppy]

@amiralies can you open a tracking issue / PR to the editor-support repository? We'll probably need @cristianoc to verify the approach

[ryyppy]

Short update: The plan is to update the Belt / stdlib modules to our own markdown based doc headers. The way editor-support needs to adhocly convert different doc header formats is pretty hacky / error prone and we want to get rid of it (also for perf reasons).

More details on that plan as soon as we are happy with the state of our documentation generator (to verify our use-cases first) which is still quite WIP.

[amiralies]

Would be happy to contribute.
Note that it would be great if we think about how we are going to keep versioned docs.

[ryyppy]

More details on the progress can be found here: rescript-lang/rescript-lang.org#359

[idkjs]

Im available to contribute.

[ryyppy]

@amiralies Would be happy to contribute.
@idkjs Im available to contribute.

One way to start off is by manually converting all the OCaml based code examples in each jscomp/others/Belt_* file to ReScript syntax. This should be fairly simple, since it would only involve changes in the comments.

Happy to review any PRs.

(you can use the rescript-syntax repo to create a binary that allows printing the ml code in res code)

[Minnozz]

(you can use the rescript-syntax repo to create a binary that allows printing the ml code in res code)

You can also do this with rescript format -stdin .ml

[ryyppy]

You can also do this with rescript format -stdin .ml

That's actually the right way to do it lol

[idkjs]

Where does one find the 4.06.1+rescript compiler? Dont see it on opam. https://github.com/rescript-lang/rescript-compiler/blob/16d3d1a3f20829dbc3d5a73a0ea2dd005ec4e084/CONTRIBUTING.md#L16

For clarification, does this task require going through the contributing.md instructions? Or do we just clone and npm install?

[idkjs]

Most of the examples assume that Belt.Array is open, which makes sense because if you are in the Belt.Array module you dont have to open it.

Do we want the examples to continue to reflect this? I am thinking that when the message pops up, I am not in the module but in my own file so the example might be more useful showing syntax as if I were not in the module file.

So

@@ocaml.text("
reverseInPlace arr reverses items in arr in place

let arr = [|10;11;12;13;14|];;
let () = reverseInPlace arr;;
arr = [|14;13;12;11;10|];;

")

Would become

let arr = [10, 11, 12, 13, 14]
let () = Belt.Array.reverseInPlace(arr)
arr == [14, 13, 12, 11, 10]

Does this make sense?