I'd really like to have type checking in doc comment code blocks right now... I've manually gone through and updated all the docs for basic-cli and basic-websever by hand and probably have broken things along the way. Sam has helped pick up some snake_case and PNC issues, but without copying the snippet into an editor it's hard to know if it's ok.
Not sure if it's a big job to add this. Even nicer, would be if the language server could provide the orange and red squiggles in the editor :smile:
If we have a markdown library this is trivial to automate
It is a big job to automate this
We currently just parse doc comments as text, and highlight them totally separately for the docs
I know but if we can convert it to markdown we could do it trivially
We'd now need to parse them in addition to the rest of the code
Let me think about that
I mean the type checking and validating the blocks
We'd probably want to do our own "close-to-markdown" parsing anyway, since the long-term goal is for us to have basically no dependencies (LLVM and Zig)
That could work
All you need to parse out is the code blocks which we already do
Even if it's parsed as markdown for us, there's still a lot of work waiting because code blocks for docs need to be treated differently in a few different ways
And then just throw them in a module or something and execute them
Of course there’s some massaging to do
The massaging is the part I'm expecting is a lot of effort
But yes in theory it's simple
Very doable if someone is committed
We don't want to support full markdown... at least I know Richard has mentioned we don't want to support html or anything like that in Doc comments.
One option would be just to provide this check with roc docs
where it's being parsed anyway
We can also do it during roc check as a separate check
So the typical path ignores comments, keeping things fast... and then for those who want to check the CI run that checks roc docs
etc will pick it up
Like Rust does
Sounds like we want to parse our own partial markdown. That means basically:
And probably bold/italics
We are gonna be doing some nice caching from the results of parsing and canonicalization
We should take advantage of the parsing work we already have in the parse crate and do it there
26 messages were moved here from #compiler development > casual conversation by Luke Boswell.
Is there a minimal scope here where we just parse out the ## ```roc
and ## ```
part and do something with it... we could leave the other parts for a future expansion right?
I think it's not that much effort to add the other stuff, the code blocks are the harder part IMO.
But we can definitely start with just code blocks
It'd help break this up
I'm just thinking that another way to break this up is to first parse as markdown and leave code blocks as text blobs
And after that, parse the code blocks themselves
But if we're optimizing for getting code blocks type-checked and everything else is okay not worrying about, then we can run in a straight line, sure
First, it'd be nice to get Richard's agreement on this, since it's a big change.
It's one thing if he thinks this is just too much work compared to other important stuff.
But it felt like the pushback last time in #contributing > Ironing out doc code blocks was around docs always needing to type check and that getting in the way of them being useful teaching tools
But if we implement the ...
keyword first, then we can probably take that pain away
Luke Boswell said:
We don't want to support full markdown... at least I know Richard has mentioned we don't want to support html or anything like that in Doc comments.
specifically I don't want to support escaping to arbitrary HTML
so that we aren't coupled to only being able to output docs to things that can render html
e.g. if we want to be able to render in an editor that doesn't include a whole browser
also yeah, I think if we have ...
I'd be open to trying this
As nice as this is, we should probably put it below everything else we're working on for 0.1.0
But if someone really wanted to implement this, I'd be happy to help them do it! It'd be very valuable
Sam Mohr said:
But if we're optimizing for getting code blocks type-checked and everything else is okay not worrying about, then we can run in a straight line, sure
My thinking here for why we might want to prioritise this part of it sooner than later is that it helps ensure documentation quality (particularly with all the breaking and syntax changes) across the ecosystem.
It's a bit of chicken and egg, but quality documentation for all the platforms & packages helps reinforce the culture around high quality roc packages, and for new people experiencing roc (who may not be experienced with the magic of Elm ecosystem)
I've been debating with myself how I would prioritise this, but I'm thinking it would be nice to have (just this code block part) before Richard's blog post and we expect a few new people to be visiting and checking things out.
So somewhere after |args|
and "string ${interpolation}
, but before we make the static-dispatch/abilities/module params etc changes.
Quick note in case it's useful: I know from integrating libcmark
into my static site builder platform that it will by default escape HTML, only parse it out if you pass a special flag.
We could maybe start with using a library, which would get us to the end result faster
Just remember that Roc doesn't want to have any deps besides LLVM and Zig in the longterm
and probably Blake3. I could see an argument for a markdown parser being a dependency though
You could find a minimal one with a liberal license and just vendor it
Last updated: Jul 06 2025 at 12:14 UTC