Reason: Parse and format comments as markdown.

[jordwalke]

We should parse doc blocks as markdown comments:

1. Parse docblock comments as MD. Incorporate a lightweight markdown parser that doesn't depend on Oasis.
2. Make sure they refmt nicely. That means the text portions would wrap, but code samples inside of comments (indented by four spaces or surrounded by tripple backticks) would remain untouched.
3. Make changes in the Reason PPX to make sure that docbloc comments are represented properly. Currently the ppx attributes include leading stars in them. These show up as ocamldoc lists, which they shouldn't. We should strip the leading stars from the comment text when parsing into ppx attributes. We might also need to convert these comments into ocamldoc format when storing them in the AST - however, I think some of this should be on merlin's end. It could have a "markdown mode", and/or it could even be the one to strip the leading stars.
4. Ensure the performance of parsing and printing has not regressed much. (Printing could be pretty expensive but that's not terrible since it only happens when reformatting).

cc @let-def about Merlin's end here. Who should be responsible for stripping leading stars from ppx comment attributes? Who should be responsible for converting it from markdown to ocamldoc?

[jordwalke]

@rgrinberg Why does omd still depend on oasis?

[jordwalke]

@rrdelaney will look into this (I'll remove this comment if that changes)

[jaredly]

I've forked Omd to fix some bugs, and I use it in both redoc and reason-language-server. Given that ocaml's parser doesn't strip leading stars, I don't think reason's should either. Let's have the AST directly represent the code that was written.
When refmt is printing out reason syntax code, then it can do parsing of the docblock so that it can reflow things. But I don't think it should do any doccomment processing one the "parse" side of things.

[bordoley]

It would be really cool if markdown code examples within comments were also run through refmt themselves.

[jaredly]

Yeah that should be totally doable 👏 (again we'd only incur the parsing + processing cost on the "print to reason" side, so compile times shouldn't be impacted)

[jaredly]

for the record here's my vendored version of omd https://github.com/jaredly/reason-language-server/tree/master/omd

[jordwalke]

@bordoley Great idea!

@jaredly: One problem is that right now merlin doesn't know if your ppx attribute doc comments were written in ocamldoc format or markdown format and it assume ocamldoc format so it doesn't strip the leading stars when rendering markdown comments in Atom. What do you suggest doing?

[hcarty]

Would it be worth supporting an attribute to specify the format of doc comments? Something like that could be coordinated with the odoc folks.

[jaredly]

@jordwalke what I do in my language server is assume it was markdown if it came from a .re(i) file, and assume ocamldoc if it came from a .ml(i). Seems to work quite well

[jordwalke]

That is probably a pretty accurate heuristic!

[jordwalke]

I've split this task into two separate ones:

• https://github.com/facebook/reason/issues/2391
• https://github.com/facebook/reason/issues/2392

Let us know if anyone wants to help with this one. It will be greatly appreciated.