Jonathan Schear (Mar 21 2024 at 23:04): Jonathan Schear (Mar 21 2024 at 23:04):I was taking a look at implementing https://github.com/roc-lang/roc/issues/6582, which would consider this to be a doc comment:
##Comment
User:{name:Str}
And make the formatter add a space:
## Comment
User:{name:Str}
Meanwhile, there's a test asserting the current behavior of treating ##Foo as a line comment. Anyone have strong opinions on how this should work? I like the behavior described in the github issue; if someone types ## without a space I would think they probably meant to write a doc comment, but auto-formatting _anything_ inside a comment might also feel a bit strange.
Some prior art: "Gofmt removes leading and trailing blank lines in doc comments. If all lines in a doc comment begin with the same sequence of spaces and tabs, gofmt removes that prefix."
cc @Anton
Ayaz Hafiz (Mar 21 2024 at 23:52):I would format it to have the space
Luke Boswell (Mar 22 2024 at 00:11):In think the way Anton described it in the Issue looks good. Two hashes ## then add a space, otherwise leave it as it is.
Richard Feldman (Mar 22 2024 at 00:14):yeah I agree with the way it's written in the issue
Richard Feldman (Mar 22 2024 at 00:15):I'd add that I think it's fine if we change the parser from "doc comment is ## followed by space" to "doc comment is ## followed by anything other than # or newline"
Jonathan Schear (Mar 22 2024 at 00:33):Sweet, sounds like consensus :)
Jonathan Schear (Mar 22 2024 at 21:08):Richard Feldman said:
"doc comment is
##followed by anything other than#or newline"
##\n is considered a doc comment right now, and I think it makes sense to give people a way to add newlines to docs using that -- https://github.com/lukewilliamboswell/roc-parser/blob/main/package/Core.roc / https://lukewilliamboswell.github.io/roc-parser/Core/ is a good example.
Relevant parser code: https://github.com/roc-lang/roc/blob/main/crates/compiler/parse/src/blankspace.rs#L437-L444
Richard Feldman (Mar 22 2024 at 21:29):oh true
Richard Feldman (Mar 22 2024 at 21:29):ok then anything other than # I guess :big_smile:
Jonathan Schear (Mar 22 2024 at 21:30):errrr actually, trying to figure out if those newlines actually end up in the markdown input...
Jonathan Schear (Mar 24 2024 at 19:36):Looks like they do! https://github.com/roc-lang/roc/pull/6597/ is ready for a look.
Last updated: Jul 05 2025 at 12:14 UTC