Reason: Comments for variable names

[chenglou]

From @jaredly’s https://twitter.com/jaredforsyth/status/972312891083849729
I think a docblock/attribute attached to a let binding, so that we can have short binding names and long prose description for said names on hover would be really nice.

[jordwalke]

We have these for module let bindings. Atom/VSCode should show the documentation for them on hover. There's just a few details that need to be improved, like the fact that you can't have leading stars on the doc comment without it being interpreted as a markdown list. Other than that, it's a great feature so far.

[zploskey]

It looks like the markdown link doesn't work in your example.

[jordwalke]

@zploskey that's probably an artifact of Atom's/LSP's rendering. As I mentioned there's some issues with it. It would be great if someone could figure out the best approach to letting us use markdown in doc-comments, with leading stars. I think the fix could be in the LSP implementation?

[zploskey]

@jordwalke I see what you mean about leading *s being interpreted as a markdown list. It looks like ocaml-language-server parses ocamldoc and renders the result to markdown. A special case in that parser grammar could probably fix that (and as far as I know we can still do lists with -). Same for links. Is it intended that doc comments be written in markdown rather than ocamldoc format? Where does that leave us with tools to generate documentation?

I'm quite keen on getting the Reason documentation story ironed out. If docs are easy to write and generate from doc comments and well integrated in the editor I expect it will help adoption. People tend to not be very excited about writing documentation so the workflow needs to be smooth for at least getting API docs.

[jordwalke]

I would prefer markdown comments as opposed to ocamldoc which no one knows. Can you show me where the assumption about ocamldoc is hard coded?

[jordwalke]

There may be some other reasons to use ocamldoc (other documentation automation tools) and if that’s the case the other approach is to parse markdown in Reason parser and convert it to ocamldoc at parse time. There are libraries for helping to parse markdown. Let me know what you think.

[zploskey]

The files relating to ocamldoc and parsing to markdown are here: https://github.com/freebroccolo/ocaml-language-server/tree/v1.0.28/src/bin/server/parser/ocamldoc

It looks like ocamldoc.intoMarkdown() gets called on hover.

[jordwalke]

I see. So a custom flag in language server which disables that for Reason won’t exactly work because we want to view docs for libraries that were written in OCaml too. We need to know the source language that the comment was written in for that to work.

It might be easiest to just convert markdown into ocamldoc on the way into the parse tree.

[jaredly]

My reason-language-server handles both ocamldoc and markdown, based on the source file format. Feel free to open an issue on the ocaml-language-server repo.