Add support for module comments.

Module comments are of the form:
```/*** stuff */```

or internally
```@@ns.doc(" stuff ")```

Author: cristianoc

src/res_comment.ml

@@ -1,10 +1,11 @@
-type style = SingleLine | MultiLine | DocComment
+type style = SingleLine | MultiLine | DocComment | ModuleComment
 
 let styleToString s =
   match s with
   | SingleLine -> "SingleLine"
   | MultiLine -> "MultiLine"
   | DocComment -> "DocComment"
+  | ModuleComment -> "ModuleComment"
 
 type t = {
   txt: string;
@@ -23,6 +24,8 @@ let isSingleLineComment t = t.style = SingleLine
 
 let isDocComment t = t.style = DocComment
 
+let isModuleComment t = t.style = ModuleComment
+
 let toString t =
   let {Location.loc_start; loc_end} = t.loc in
   Format.sprintf "(txt: %s\nstyle: %s\nlocation: %d,%d-%d,%d)" t.txt
@@ -34,11 +37,13 @@ let toString t =
 let makeSingleLineComment ~loc txt =
   {txt; loc; style = SingleLine; prevTokEndPos = Lexing.dummy_pos}
 
-let makeMultiLineComment ~loc ~docComment txt =
+let makeMultiLineComment ~loc ~docComment ~standalone txt =
   {
     txt;
     loc;
-    style = (if docComment then DocComment else MultiLine);
+    style =
+      (if docComment then if standalone then ModuleComment else DocComment
+      else MultiLine);
     prevTokEndPos = Lexing.dummy_pos;
   }
 

src/res_comment.mli

@@ -10,10 +10,13 @@ val setPrevTokEndPos : t -> Lexing.position -> unit
 
 val isDocComment : t -> bool
 
+val isModuleComment : t -> bool
+
 val isSingleLineComment : t -> bool
 
 val makeSingleLineComment : loc:Location.t -> string -> t
-val makeMultiLineComment : loc:Location.t -> docComment:bool -> string -> t
+val makeMultiLineComment :
+  loc:Location.t -> docComment:bool -> standalone:bool -> string -> t
 val fromOcamlComment :
   loc:Location.t -> txt:string -> prevTokEndPos:Lexing.position -> t
 val trimSpaces : string -> string

src/res_core.ml

@@ -5364,6 +5364,16 @@ and parseStructureItemRegion p =
     let loc = mkLoc startPos p.prevEndPos in
     Parser.endRegion p;
     Some {structureItem with pstr_loc = loc}
+  | ModuleComment (loc, s) ->
+    Parser.next p;
+    Some
+      (Ast_helper.Str.attribute ~loc
+         ( {txt = "ns.doc"; loc},
+           PStr
+             [
+               Ast_helper.Str.eval ~loc
+                 (Ast_helper.Exp.constant ~loc (Pconst_string (s, None)));
+             ] ))
   | AtAt ->
     let attr = parseStandaloneAttribute p in
     parseNewlineOrSemicolonStructure p;
@@ -6088,6 +6098,16 @@ and parseSignatureItemRegion p =
     parseNewlineOrSemicolonSignature p;
     let loc = mkLoc startPos p.prevEndPos in
     Some (Ast_helper.Sig.attribute ~loc attr)
+  | ModuleComment (loc, s) ->
+    Parser.next p;
+    Some
+      (Ast_helper.Sig.attribute ~loc
+         ( {txt = "ns.doc"; loc},
+           PStr
+             [
+               Ast_helper.Str.eval ~loc
+                 (Ast_helper.Exp.constant ~loc (Pconst_string (s, None)));
+             ] ))
   | PercentPercent ->
     let extension = parseExtension ~moduleLanguage:true p in
     parseNewlineOrSemicolonSignature p;
@@ -6318,6 +6338,7 @@ and parseAttributes p =
  *)
 and parseStandaloneAttribute p =
   let startPos = p.startPos in
+  (*  XX *)
   Parser.expect AtAt p;
   let attrId = parseAttributeId ~startPos p in
   let payload = parsePayload p in

src/res_parser.ml

@@ -54,6 +54,11 @@ let docCommentToAttributeToken comment =
   let loc = Comment.loc comment in
   Token.DocComment (loc, txt)
 
+let moduleCommentToAttributeToken comment =
+  let txt = Comment.txt comment in
+  let loc = Comment.loc comment in
+  Token.ModuleComment (loc, txt)
+
 (* Advance to the next non-comment token and store any encountered comment
    * in the parser's state. Every comment contains the end position of its
    * previous token to facilite comment interleaving *)
@@ -72,6 +77,11 @@ let rec next ?prevEndPos p =
       p.prevEndPos <- prevEndPos;
       p.startPos <- startPos;
       p.endPos <- endPos)
+    else if Comment.isModuleComment c then (
+      p.token <- moduleCommentToAttributeToken c;
+      p.prevEndPos <- prevEndPos;
+      p.startPos <- startPos;
+      p.endPos <- endPos)
     else (
       Comment.setPrevTokEndPos c p.endPos;
       p.comments <- c :: p.comments;

src/res_printer.ml

@@ -5096,7 +5096,12 @@ and printAttribute ?(standalone = false) ~customLayout
               Pstr_eval ({pexp_desc = Pexp_constant (Pconst_string (txt, _))}, _);
           };
         ] ) ->
-    Doc.concat [Doc.text "/**"; Doc.text txt; Doc.text "*/"]
+    Doc.concat
+      [
+        Doc.text (if standalone then "/***" else "/**");
+        Doc.text txt;
+        Doc.text "*/";
+      ]
   | _ ->
     Doc.group
       (Doc.concat

src/res_scanner.ml

@@ -546,12 +546,11 @@ let scanSingleLineComment scanner =
 
 let scanMultiLineComment scanner =
   (* assumption: we're only ever using this helper in `scan` after detecting a comment *)
-  let docComment =
-    peek2 scanner = '*'
-    && peek3 scanner <> '/'
-    (* no /**/ *) && peek3 scanner <> '*' (* no /*** *)
+  let docComment = peek2 scanner = '*' && peek3 scanner <> '/' (* no /**/ *) in
+  let standalone = docComment && peek3 scanner = '*' (* /*** *) in
+  let contentStartOff =
+    scanner.offset + if docComment then if standalone then 4 else 3 else 2
   in
-  let contentStartOff = scanner.offset + if docComment then 3 else 2 in
   let startPos = position scanner in
   let rec scan ~depth =
     (* invariant: depth > 0 right after this match. See assumption *)
@@ -573,7 +572,7 @@ let scanMultiLineComment scanner =
   let length = scanner.offset - 2 - contentStartOff in
   let length = if length < 0 (* in case of EOF *) then 0 else length in
   Token.Comment
-    (Comment.makeMultiLineComment ~docComment
+    (Comment.makeMultiLineComment ~docComment ~standalone
        ~loc:
          Location.
            {loc_start = startPos; loc_end = position scanner; loc_ghost = false}

src/res_token.ml

@@ -96,6 +96,7 @@ type t =
   | Import
   | Export
   | DocComment of Location.t * string
+  | ModuleComment of Location.t * string
 
 let precedence = function
   | HashEqual | ColonEqual -> 1
@@ -207,6 +208,7 @@ let toString = function
   | Import -> "import"
   | Export -> "export"
   | DocComment (_loc, s) -> "DocComment " ^ s
+  | ModuleComment (_loc, s) -> "ModuleComment " ^ s
 
 let keywordTable = function
   | "and" -> And

tests/parsing/other/docComments.res

@@ -1,6 +1,12 @@
+/*** This is a module comment */
+
+/*** This is another module comment */
+
 /** This is a doc ✅ comment */
 let z = 34
 
+@@ns.doc("And this is a ns.doc module annotation")
+
 @ns.doc("And this is a ns.doc ✅ annotation")
 let q = 11
 

tests/parsing/other/expected/docComments.res.txt

@@ -1,4 +1,7 @@
+[@@@ns.doc " This is a module comment "]
+[@@@ns.doc " This is another module comment "]
 let z = 34[@@ns.doc " This is a doc \226\156\133 comment "]
+[@@@ns.doc {js|And this is a ns.doc module annotation|js}]
 let q = 11[@@ns.doc {js|And this is a ns.doc ✅ annotation|js}]
 type nonrec h = int[@@ns.doc
                      " This\n  * is a multi-line\n  multiline doc comment\n  "]

tests/printer/comments/docComments.res

@@ -1,11 +1,17 @@
+/*** This is a module comment */
+
+/*** This is another module comment */
+
 /** This is a doc ✅ comment */
 let z = 34
 
+@@ns.doc("And this is a ns.doc module annotation")
+
 @ns.doc("And this is a ns.doc ✅ annotation")
 let q = 11
 
 /** This
   * is a multi-line
   multiline doc comment
   */
-type h = int
+type h = int

tests/printer/comments/expected/docComments.res.txt

@@ -1,6 +1,12 @@
+/*** This is a module comment */
+
+/*** This is another module comment */
+
 /** This is a doc ✅ comment */
 let z = 34
 
+/***And this is a ns.doc module annotation*/
+
 /**And this is a ns.doc ✅ annotation*/
 let q = 11