reasonml
[refmt] Module-level doc comment not respected
Input
/** module-level docs */
open A;
Reformatted
/** module-level docs */
open A;
Expected Output
[@@ocaml.doc " module-level docs "]
open A
Actual Output due to Reformatting
open A[@@ocaml.doc " module-level docs "]
The removal of the space between the module-wide comment and the module open seems to make the compilation think the doc annotation is for the open rather than the module.
I'm struggling with this, and my current workaround is to include a top-level abstract type that will be displayed. This of course is undesirable.
Happy to jump into the reformatter code if I can get a few pointers 🙌
@ostera top-level docblock comments need to end in a semicolon :)
/** module-level docs */;
open A;
should do it.
Is there any particular reason this is required? And is it desirable to keep it working this way?
Ah, yeah, I was puzzled by this too. Would love to let it (;) go away. On Wed, 12 Sep 2018 at 08:59 Leandro Ostera [email protected] wrote:
Is there any particular reason this is required? And is it desirable to keep it working this way?
— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/facebook/reason/issues/2177#issuecomment-420522121, or mute the thread https://github.com/notifications/unsubscribe-auth/AAB3gsP8Y2Zw3d06adTQRJcRxsY3Lg6Wks5uaKLUgaJpZM4WiKkv .
I think the reason it's required is because doc comments are parsed into documentation attributes in the AST. The semicolon disambiguates the target of the doc attribute.
Unfortunately, adding ';' at the end of the doc block makes it disappear when running odoc. Not sure if that's related to this issue.
