Incorrect parsing of ocamldoc, module doc gets attached to first declaration

[Lupus]

This try reason link illustrates the issue.

I tried to document my module in .rei file and was unable to make odoc generate html which included module level documentation. I've refmt-printed my .rei to .mli, and found that documentation got attached to first declaration in my module. I've manually added doc comments to .mli, generated documentation and it included module level doc as expected.

dune version: 1.10.0
esy version: 0.5.6
refmt version: Reason 3.3.7 @ 43efc14

[Lupus]

Looks like adding ; after module-level comment fixes parsing. I figured it out while trying to parse correct .mli back to .rei and noticed that refmt added that ;. Illustrated in this try reason link.

[Lupus]

I've opened an issue in odoc project for this as well, as I'm not sure about the root cause of doc being ingnored.

If I try to generate doc from .mli which was printed from .rei with aforementioned workadound, module level doc gets ignored by odoc for .mli file as well. Looks like that [@@@ocaml.doc "..."] is not understood by odoc.

[Lupus]

Glancing at output of ocamlc -dparsetree for both refmt printed .mli and hand-written .mli with semantically same content, there is difference in Psig_attribute, for native hand-written comment it's "ocaml.text" while for refmt generated one it's "ocaml.doc".

[Lupus]

In case it's important, I'm using OCaml 4.06.0.

[Lupus]

For others running into this issue: workaround to get docs done:

[@ocaml.text "
{1 Overview}

This module implements <....>
<....>
"];

/** This is some type t */
type t;

/* rest of your module <.....> */

[mlms13]

Just to add to the findings...

• The [@ocaml.text] solution works! Thank you!
• I can't seem to use {1 Heading} style comments in reason syntax at all unless I use [@ocaml.text ...] instead of /** ... */

[Lupus]

I believe that has nothing to do with Reason. ocaml.text is floating module level documentation, while /** ... */ that is attached to certain ast nodes is ocaml.doc, and the latter probably does not support multi-section formatting, which makes sense.

Btw, you could use [@ocaml.text {| ... |}] to avoid issues with escaping '"' inside the documentation (if you have a snippet of code inside for example).

[jordwalke]

Isn't the issue that you need a semicolon after the first comment?

[jordwalke]

I'm told there's two issues. One is the semicolon (that's easy to teach people) and the other is that we need to correctly translate free floating doc comments that have semicolons. Should be an easy fix.