Luke Boswell (Oct 18 2022 at 04:13): Luke Boswell (Oct 18 2022 at 04:13):Should Types have their doc comments included in the generated html? I've been trying to follow along and figure out why they aren't being included, but it's a long way down the rabbit hole. I'm currently looking at peg_grammar and highlight_parser and I'm pretty sure I'm way off course. Can anyone help me understand why the comments for types aren't being generated?
Richard Feldman (Oct 18 2022 at 04:38):I don't know, but I do know it's a bug - types should definitely be included in the docs!
Richard Feldman (Oct 18 2022 at 04:40):I'm not sure where the problem is happening, but I'd look for code using the Rust CommonMark parser - that should be where we parse the doc comments, so it ought to be a starting point at least!
Brian Carroll (Oct 18 2022 at 04:43):I don't know the reason either but if you feel you're veering off course then I recommend inserting some debug print statements to look at variable values. dbg!(&some_variable);. The & is usually enough to pacify the borrow checker.
Luke Boswell (Oct 18 2022 at 05:12):Can I confirm the design/intent for comments, # is for inline comments while ## is document comments for inclusion in generated docs? Using # as a line comment should not be permitted? or is that for comments that are intentionally left out of generated docs?
Luke Boswell (Oct 18 2022 at 05:14):I'm just adding a section on comments into the tutorial for future reference.
Anton (Oct 18 2022 at 06:12):peg_grammar and highlight_parser are currently unused for the docs generation.
Richard Feldman (Oct 18 2022 at 07:57):yeah # is for comments intentionally left out of docs, and ## is for doc comments!
Luke Boswell (Oct 18 2022 at 08:49):Also, I think I've finally figured out the issue is I was referring to above... I was concerned about at the opaque types which are not currently being generated to html. I am reasonably sure the doc comments are there in the LoadedModule but I think they are just assigned NoTypeAnn for the TypeAnnotation specifically line 247 in crates/compiler/load_internal/src/docs.rs. Not sure how easy this is to add, my Rust is pretty basic.
Luke Boswell (Oct 18 2022 at 09:24):I've added a PR #4357 which adds some discussion on comments to the Tutorial. There was some information in the Roc for Elm devs, so I used that and expanded it based on what I have learn't about comments so far. It should be ready for review.
Anton (Oct 18 2022 at 09:24):Thanks @Luke Boswell, I'll take a look :)
Last updated: Jul 06 2025 at 12:14 UTC