✨ Consider keeping doc comments in the parsed AST.

[hayleigh-dot-work]

I'm building some alternative docs for lustre and currently have to copy each definition + doc comment by hand into whatever I'm using to write/build docs. I thought about using glance to at least semi-automate this process but with no doc comments in the AST it's a non-starter for me.

I can see access to doc comments useful for other projects too, so maybe we could think about adding this in the future.

[lpil]

Would you want the documentation for functions, or do you want specifically comments?

[bcpeinhardt]

I know I'm not the person who opened this but I like the idea of just doc comments. It wouldn't complicate the AST hardly at all. I imagine it'd be an update like

pub type Definition(definition) {
  Definition(docs: Docs, attributes: List(Attribute), definition: definition)
}

[cdaringe]

i'd like to 'em attached to each node 😄 e.g. Node(comments: List(Comment), ..)

that way i can AST -> transform -> AST with comments fully functional.

JS has a commentless AST, and every parser does it differently, if at all. very painful over there, specifically because comments are used by coverage instrumentation tools, which get totally borked easily in different projects.

[lpil]

That would make working with the AST significantly more difficult as you could no longer do pattern matching due to the structure of the tree being unpredictable depending on whether there are comments.

Glance also doesn't preserve positional information so you wouldn't be able to put them back in the same place, or preserve formatting in general, so it would result in different code at the end of that.

We could add a comment field to every node, but that's quite verbose and loses positioning again.