I am currently spear-heading a somewhat annoying task that I could eventually require help with.
We want to upstream the latest API doc texts from rescript-lang .org to the actual Belt / Js source files within the rescript-compiler repo. As soon as this is done, we will convert the actual
mli files to
This will give us following advantages:
- Familiar syntax for core modules (when e.g. cmd-clicking on
- On-hover docs contain examples in ReScript syntax (instead of ML)
- It’s a first step to switch over to markdown for doc headers. Easier to get started to write doc strings, formatting works with most editors / LSP setups OOTB. Less work for us to generate the required output for rescript-lang .org.
Here’s the pending PR: https://github.com/rescript-lang/rescript-compiler/pull/5361
As soon as we synced and transformed all the files, the next step would be the automatic extraction of all the docs via a simple extraction tool (as seen on my experimental-docgen branch on the syntax repo).
Additionally, we will need to teach the ReScript syntax on how to parse / print docstring syntax (right now we rely on
ocaml.doc decorators). But this will be another separate topic to work on.
If you are interested in helping me syncing the docs, here’s how:
- Check out the aforementioned PR
- Take a file from the checklist
- Find the relevant md doc file on the rescript-lang org repo (the files stored in
- Copy all the docstring texts (including the codefences with examples) to the
mlidoc headers, including the general module description in the (the
<Intro>semantics should be omitted for now)
- Send a PR to the pending PR and ping me in case I am unresponsive. I will try to merge and tick the checklist as quickly as possible
Rinse and repeat for all the
Belt modules, then we will do the same thing for
Js. Let me know if you are keen to help!
(Note: There’s probably ppl asking why we are not reusing
jsdoc for the docstring syntax. We find the less-frills approach a little more appealing, in a similar vain as Go does… just let the user write docs without dictating too much format… we will try to do the rest. There were some thoughts to generate
md files the same way as we generate
.js files: Automatically without much ceremony on generating docs separately. Releasing docs would be as easy as checking them into your git repository. We will explore and experiment as we go.)