Odoc parser does not render comments properly

[Lomand]

In the current state of affairs only the first line of the comment is treated as such, the rest is rendered as is All grammar is ignored, even in the first line.

Compare this to working odoc parser in ocaml-platform

Demo: https://github.com/Lomand/rescript-broken-autocomplete-jsx/blob/master/src/Demo.res

[cristianoc]

Odoc comments are not supported (there's no odoc parser; earlier versions had an often broken parser). Doc comments are getting gradually converted to markdown: https://github.com/rescript-lang/rescript-compiler/blob/2f0201f471df94dc4650966132c011b97ff09a1f/jscomp/others/belt_List.mli#L241

[Lomand]

Ok, looks like anyone who wants to generate docs from the source code is out of luck. Such a shame

[zth]

There was some work on documentation generation by the core team here https://github.com/rescript-lang/syntax/tree/experimental-docgen. But, that work seems to have gone stale.

[ryyppy]

Yeah the docgen stuff I wrote extracts all the markdown comments into a JSON file that can actually be processed outside of OCaml tooling... a huge issue we originally had with odoc back then.

One thing that's still missing though is semantic /**/ parsing, so we currently rely on @ocaml.doc as our comment marker still.

[amiralies]

I think parsing /** */ should be easy if we agree on its syntax. i.e /** {content} */ -> multiline comment and annotate with ocaml.doc (or whatever). /* {content} */ -> multiline comment

[zth]

Closing this as I believe this either isn't an issue anymore, or is going to be fixed whenever core modules are converted to res + markdown.