Formatting of MDX blocks in doc comments

[NathanReb]

We recently added support for mli files in MDX which means that now you write ocaml toplevel blocks in your doc comments and have MDX verify that for you.

This means code blocks in doc comments may now contain MDX toplevel blocks which for now have a syntax of their own that is not pure OCaml:

(** This functions simply returns the result of addition of its argument.
    {[
      # let x = 2 in
        add x 1;;
      - : int = 3
    ]} *)
val add : int -> int -> int

The format of those blocks is:

# <toplevel-phrase>;;
<eval-or-error>
# <toplevel-phrase>;;
<eval-or-error>
...

Where toplevel-phrase is a valid OCaml toplevel phrase, eval-or-error is/should be considered arbitrary text and where both phrases and evals can span over mulitiple lines.

It would be nice if we could somehow get ocamlformat to format the toplevel phrases properly while leaving out the evals and errors.

Please let me know what you think would be an appropriate way to get mdx, ocamlformat and odoc to collaborate on this matter.

I'm of course happy to help implement whatever solution we may chose!

[NathanReb]

CC @diml @jsomers @jonludlam

[jberdine]

From the ocamlformat side, I think that what we'd need is for this new form of doc comments to be added to the odoc ast, and preferably the documentation too.

I guess that there is a parser for these for the MDX support. Is that something that could be extracted and worked into a PR for odoc?

[NathanReb]

It could definitely be extracted into odoc! @jonludlam would you accept such a PR?

Atm MDX uses odoc parser so it would even further simplify the whole thing if it the block content parsing could be factored into odoc and shared between mdx for evaluation and ocamlformat for formatting!