Writing documentation in ReScript

,
1

Hi,

Is there a workflow for writing source code documentation, like .mli + odoc in OCaml?

Thanks

1 Like
2

Not yet. But the evolution in this direction is happening right now. See:

I think very soon (v10.1?) ReScripters will be able to write /** ... */ comments with Markdown and see their docs auto-generated.

2 Likes
3

I’ve seen @ocaml.doc which content is shown on hover.

4

Exactly! As for right now, the newest syntax changes include parsing and printing of /** */ headers for types, values etc, but currently not for modules (see this open issue).

The rescriptified files for Js and Belt are already generated, I just need to verify that everything is still working and make sure no information was lost.

For the workflow, the doc headers will be kept simple by following GH flavoured markdown. So if you are keen on writing docs, just use markdown.

Yes, right now ocaml.doc("...") is needed for the editor support, in the future we will automatically reprint ocaml.doc("") into /** */. It’s a little cumbersome to look at right now, but with v10 it will be a simple rescript format to make it look nice.

(kinda related: in the future, we will parse /** */ into a ReScript doc attribute instead of ocaml.doc to not mix up doc string semantics of both platforms)

4 Likes