Unshipped9094 (Jan 28 2025 at 03:23): Unshipped9094 (Jan 28 2025 at 03:23):Has there been any discussions around having doc tests in Roc?
Heard an episode of software unscripted where Richard says something along the lines of : "We have new people coming in and trying this out for the first time and sometimes that's how we find out an example in our docs is no longer valid".
Some languages allow you to take your docstring for a function and embed an example with an expected response, which will then get tested. The idea being that you end up with nicely formatted examples in your docs as well as the knowledge that those examples are correct. Great for preventing drift between your docs and the code itself.
And of course, the easiest functions to test are pure functions, so this seems like it could be relatively low hanging fruit.
Sam Mohr (Jan 28 2025 at 03:24):I have proposed something along these lines here:
Sam Mohr (Jan 28 2025 at 03:26):I think with the plan to add the ... ellipsis keyword (issue) (#ideas > Adding an ellipsis `...` keyword ), we have unblocked what we'd need to make doc tests doable without making docs less readable when they also test code
Sam Mohr (Jan 28 2025 at 03:28):However, we have not agreed to move in this direction yet. It's likely something that would get implemented after the 0.1.0 initial release push, which is focused around stability and whatever features/work we need for that to happen
Luke Boswell (Jan 28 2025 at 03:38):Yeah I definitely think we want something like this eventually. It's been discussed before a few times, though I don't have an easy reference at hand.
Unshipped9094 (Jan 28 2025 at 03:50):Could be really cool to have something like this that doesn't have to be directly in the actual doc for a function or module. I always imagine having some kind of hybrid between source code and a code notebook - basically think of a markdown doc that has some code snippets in there, except you have some tool that takes the code snippets in there and type checks and/or executes all of them.
Unshipped9094 (Jan 28 2025 at 03:51):The idea being you can have a guide or tutorial that has those nice same guarantees as doc strings that have been tested
Sam Mohr (Jan 28 2025 at 05:37):2 things:
roc check on a markdown file that has Roc snippets in it, we'll typecheck them Luke Boswell (Jan 28 2025 at 09:02):
- I don't think we have a Jupyter Notebook hookup yet, but it's basically what you're describing and it should be very doable to implement with a Roc platform!
This reminds me, I'm pretty sure @Ayaz Hafiz wrote a kernel for roc to use with Jypter Notebooks.
Luke Boswell (Jan 28 2025 at 09:03):I think this is the diff for it... not sure if it still works or anything https://github.com/roc-lang/roc/compare/main...patch-for-jupyter-kernel
Anton (Jan 28 2025 at 09:48):that doesn't have to be directly in the actual doc for a function or module
It's very easy for things to get out of sync if the docs are not right next to the code. Even if the code is checked automatically, explanations will drift.
Anton (Jan 28 2025 at 09:49):It does make sense for a tutorial though. Like Sam said, we almost have this ready for use, just need to support a nice way of hiding lines of Roc code.
Anthony Bullard (Jan 28 2025 at 11:12):Doc Tests are one of the best innovations in programming languages in the past decade or so in my opinion
Unshipped9094 (Jan 28 2025 at 15:28):Typechecking on a markdown doc is a pretty cool start
Unshipped9094 (Jan 28 2025 at 15:29):Anton said:
It does make sense for a tutorial though. Like Sam said, we almost have this ready for use, just need to support a nice way of hiding lines of Roc code.
Yeah, more thinking of a tutorial or even a section guide. For example, some ecosystems, the docs will have not only the docs for the functions and modules, but also being able to have other related guides that aren't locked to one specific function
Last updated: Jun 16 2026 at 16:19 UTC