The problem at hand
ReasonML documentation is currently “split” between ReasonML and BuckleScript. In the discord channel, I often see questions about Reason being answered by referring to documentation written for BuckleScript. All of the documentation for Belt and Js appears to be in BuckleScript format. Even the ReasonML API links, such as Array have declarations in ReasonML but the explanations in BuckleScript style (or possibly the old no-parentheses ReasonML style).
This reminds me of the situation in the early days of Elixir, where a lot of the documentation referred you to Erlang docs.
Solving the problem
Elixir has developed its own documentation, generated from its source, which is separate from the Erlang code. For example, the source for Elixir
genServer is totally different from the Erlang
gen_server documentation – which is not generated from the source code. This sort of solution requires a lot of effort.
It would be far preferable to generate both ReasonML and BuckleScript documentation from a single source.
docre helps greatly in this regard. For example, this is the conversion of
Belt_List, which does a respectable job. It generates quite a few
Unable to refmt code with a syntax error because (as per the author of
docre) “…lots of the examples assume they’re in a top-level, which doesn’t work with
The next step, as I see it, would be to modify the existing BuckleScript documentation so that the examples are all translatable via
docre, and yes, I am willing to assist with this.