This looks fantastic @jonludlam!
Have you considered integrating a doctest-like feature (aka “testable examples”) into odoc?
If documenting could be merged into one’s (basic) testing workflow, I’m sure it would encourage even more adoption and usage.
Here are a few implementations of what I’m talking about:
- doctest — Test interactive Python examples — Python 3.11.1 documentation
- Testable Examples in Go - The Go Programming Language
- Documentation tests - The rustdoc book
- ExUnit.DocTest — ExUnit v1.13.4
- GitHub - sol/doctest: An implementation of Python's doctest for Haskell
This feature/concept is integrated into the default Go, Rust and Elixir tool chains (not sure about Python which is were the idea came from years ago).
The doctest feature for Haskell is supported by the default vscode tooling and easily integrated into a cabal workflow. It’s very nice to use, and looks like this:
This comment turns into executable code:
From the caller’s perspective:
This is what happens if I change my function input and click “Refresh” (the feedback is instantaneous).
Or clear the line and let the tooling auto-fill the output by clicking on “Evaluate”, similar to a dune promote workflow.
