Thoughts on unifying ReasonML Documentation


#1

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 docre

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.


#2

It would be nice if the BuckleScript documentation had a way to toggle OCaml/Reason syntax instead of showing both options–generally speaking, I need to hide as much complexity as possible while I’m learning something new, and this could help reduce the mental overhead for newcomers like me. (My experience when reading the docs usually goes something like: “Oh, here’s the example code. Wait, this doesn’t make sense. Oh, it’s OCaml. [skip down] Ah, here’s the Reason code that I’m trying to learn.” Multiply times number of code samples I read.)


About documentation, immutability, first-class functions and dynamic and static environments