Are there plans for integrated documentation and testing in rescript?

IMO one of the great features of Rust is that there is one simple, easy, and idiomatic way to write documentation and tests built into the language. Rust libraries consistently impress me with the levels of useful documentation and on top of that it’s all easy to read because it’s all in a standard format. Examples in doc comments being auto-run as tests I think is a brilliant way to ensure that docs don’t get stale and examples are of high quality. I think rescript would be wise to emulate rust in docs and testing!

A pain point of JS is that there are far too many ways to do testing and documentation. It’s easy to fall into analysis paralysis and it adds mental burdens to developers to need to find a solution for docs/tests rather than simply using a standard system built into the language. It also makes contribution significantly harder when a project uses a system of docs/tests that you aren’t familiar with. I think it could be a big selling point for rescript if this were a built in thing that “just works” the way it does in rust.

Are there currently any plans for integrating official tooling for documentation and testing into the rescript language? If not, why not? What are the tradeoffs?

For testing I’m not sure.
but for doc generation there is an official WIP tool.

cc/ @ryyppy can we do some project management stuff on the docgen tool and ask community to help pushing it forward?

3 Likes

shameless plug, but if you like inline testing à la rust, we got you covered here :slight_smile:

8 Likes

Thanks for the shameless plug, that looks amazing!

1 Like

That inline-test ppx is great! Thank you! Doesn’t play nice with rescript-test but I think that’s an issue with rescript-test.

Is there a possibility that inline tests or even examples-as-tests in docs could be mainlined into the rescript compiler? I think having one idiomatic and consistent way to do docs+tests would likely be extremely beneficial, especially to a language with a small community (so far).

1 Like

I think we only tested it with jest and Zora, maybe rescript-test has some special workflow, don’t hesitate to create an issue!

There should definitely be a standard for documentation in rescript, I have no idea what’s the current state of the WIP.