Parse markdown comments *into* ocamldoc.

[jordwalke]

Problem We want all the tooling to support markdown comments for Reason modules.
This includes merlin, odoc, and reason-vscode and any others.

• Here's for odoc.

Approach one: Have each tool support markdown (merlin, odoc) for Reason syntax. This issue explores doing so in odoc.
Approach two (this github issue): Explore parsing markdown comments into ocamldoc syntax on the way in.

Approach:

• In the Reason parser, for each docblock comment (which is modeled as a ppx attribute) /**, on the way in into the AST, parse some subset of markdown, then convert it back into a string in the ocamldoc form. For example, if you've parsed SingleBacktickCode(str) - then in the AST store it as [str] which is the ocamldoc syntax. Do the same thing for links, and others. A large set of ocamldoc's features have no markdown equivalent and that's okay, we can still use those too. For example {!ModuleName} would just be perceived as plain text in markdown, it won't parse, but then all the other ocamldoc based tools will make sense of it.

• Make sure the text is printed in refmt in its exact original form, not performing the substitutions.

• Explore if approach two is the right one (poke holes in it).

• Propose a mapping from markdown-light to ocamldoc syntax. (Comment on this task with your own ideas/observations).

• Implement this in the parser.

• Make sure the approach doesn't slow things down too much when compiling (heuristics like looking for any markdown token at the beginning of any newline or backtick throughout would work pretty well).

• Make sure that markdown parsing failures never crash the parser.

[avsm]

If you do use the ocaml omd parser, we'd appreciate you using the trunk version which is a big rewrite that is compatible with CommonMark that we're currently preparing for release. contributions welcome, e.g. ocaml-community/omd#181