Fix doc-comments '*)' exceeding the margin

This change applies to doc-comments and regular comments parsed as doc-comments.
ocaml-ppx · May 14, 2024 · ad31288 · ad31288
1 parent 356ec71
commit ad31288
Show file tree

Hide file tree

Showing 19 changed files with 104 additions and 76 deletions.
diff --git a/lib/Cmts.ml b/lib/Cmts.ml
@@ -554,14 +554,23 @@ module Doc = struct
           let l = List.last_exn lines in
           (is_only_whitespaces h, is_only_whitespaces l)
     in
+    let force_trailing_space =
+      String.length txt > 1 && String.ends_with_whitespace txt
+    in
     let txt = if pre_nl then String.lstrip txt else txt in
     let txt = if trail_nl then String.rstrip txt else txt in
     let parsed = Docstring.parse ~loc txt in
     (* Disable warnings when parsing of code blocks fails. *)
     let quiet = Conf_t.Elt.make true `Default in
     let conf = {conf with Conf.opr_opts= {conf.Conf.opr_opts with quiet}} in
-    let doc = Fmt_odoc.fmt_parsed conf ~fmt_code ~input:txt ~offset parsed in
     let open Fmt in
+    let trailing_space =
+      if (not trail_nl) && force_trailing_space then str " " else noop
+    in
+    let doc =
+      Fmt_odoc.fmt_parsed conf ~trailing_space ~fmt_code ~input:txt ~offset
+        parsed
+    in
     hvbox 2
       ( pro
       $ fmt_if pre_nl (break 1000 1)

diff --git a/lib/Fmt_ast.ml b/lib/Fmt_ast.ml
@@ -413,7 +413,7 @@ let fmt_parsed_docstring c ~loc ?pro ~epi input parsed =
   let doc = Fmt_odoc.fmt_parsed c.conf ~fmt_code ~offset ~input parsed in
   Cmts.fmt c loc
   @@ vbox_if (Option.is_none pro) 0
-       (fmt_opt pro $ wrap (str "(**") (str "*)") doc $ epi)
+       (fmt_opt pro $ hovbox 0 (str "(**" $ doc $ str "*)") $ epi)
 
 let docstring_epi ~standalone ~next ~epi ~floating =
   let epi = if Option.is_some next then force_newline else fmt_opt epi in

diff --git a/lib/Fmt_odoc.ml b/lib/Fmt_odoc.ml
@@ -372,20 +372,27 @@ let beginning_offset (conf : Conf.t) input =
     whitespace_count
   else min whitespace_count 1
 
-let fmt_parsed (conf : Conf.t) ~fmt_code ~input ~offset parsed =
+let fmt_parsed (conf : Conf.t) ?trailing_space ~fmt_code ~input ~offset
+    parsed =
   let open Fmt in
   let begin_offset = beginning_offset conf input in
   (* The offset is used to adjust the margin when formatting code blocks. *)
   let offset = offset + begin_offset in
   let fmt_code conf ~offset:offset' ~set_margin input =
     fmt_code conf ~offset:(offset + offset') ~set_margin input
   in
+  let trailing_space =
+    match trailing_space with
+    | Some sp -> sp
+    | None ->
+        fmt_if
+          (String.length input > 1 && String.ends_with_whitespace input)
+          space_break
+  in
   let fmt_parsed parsed =
     str (String.make begin_offset ' ')
     $ fmt_ast conf ~fmt_code parsed
-    $ fmt_if
-        (String.length input > 1 && String.ends_with_whitespace input)
-        (str " ")
+    $ trailing_space
   in
   match parsed with
   | _ when not conf.fmt_opts.parse_docstrings.v -> str input

diff --git a/lib/Fmt_odoc.mli b/lib/Fmt_odoc.mli
@@ -23,6 +23,7 @@ val fmt_ast :
 
 val fmt_parsed :
      Conf.t
+  -> ?trailing_space:Fmt.t
   -> fmt_code:fmt_code
   -> input:string
   -> offset:int

diff --git a/test/passing/tests/break_separators-after.ml.err b/test/passing/tests/break_separators-after.ml.err
@@ -1 +0,0 @@
-Warning: tests/break_separators.ml:289 exceeds the margin

diff --git a/test/passing/tests/break_separators-after.ml.ref b/test/passing/tests/break_separators-after.ml.ref
@@ -287,7 +287,8 @@ let foooooooooooo =
 
 let foooooooooooo =
   { foooooooooooooo with
-    (* foooooooooooooooo fooooooooooooooooooooooooo foooooooooooooooooooooo *)
+    (* foooooooooooooooo fooooooooooooooooooooooooo foooooooooooooooooooooo
+    *)
     fooooooooooooooooooooooooooooo= fooooooooooooo;
     fooooooooooooo= foooooooooooooo }
 
@@ -381,6 +382,7 @@ let () =
   match x with
   | ( _,
       (* verrrrrrrrrrrrrrrrrrrrrrrry looooooooooooooooong line 1
-         veeeeeeeeeeeeeeeeeeeeeryyyy loooooooooooooooooong line 2 *)
+         veeeeeeeeeeeeeeeeeeeeeryyyy loooooooooooooooooong line 2
+      *)
       Some _ ) ->
       x
diff --git a/test/passing/tests/break_separators-after_docked.ml.err b/test/passing/tests/break_separators-after_docked.ml.err
@@ -1,2 +1 @@
-Warning: tests/break_separators.ml:324 exceeds the margin
-Warning: tests/break_separators.ml:334 exceeds the margin
+Warning: tests/break_separators.ml:335 exceeds the margin
diff --git a/test/passing/tests/break_separators-after_docked.ml.ref b/test/passing/tests/break_separators-after_docked.ml.ref
@@ -322,7 +322,8 @@ let foooooooooooo =
 let foooooooooooo =
   {
     foooooooooooooo with
-    (* foooooooooooooooo fooooooooooooooooooooooooo foooooooooooooooooooooo *)
+    (* foooooooooooooooo fooooooooooooooooooooooooo foooooooooooooooooooooo
+    *)
     fooooooooooooooooooooooooooooo= fooooooooooooo;
     fooooooooooooo= foooooooooooooo;
   }
@@ -430,6 +431,7 @@ let () =
   match x with
   | ( _,
       (* verrrrrrrrrrrrrrrrrrrrrrrry looooooooooooooooong line 1
-         veeeeeeeeeeeeeeeeeeeeeryyyy loooooooooooooooooong line 2 *)
+         veeeeeeeeeeeeeeeeeeeeeryyyy loooooooooooooooooong line 2
+      *)
       Some _ ) ->
       x
diff --git a/test/passing/tests/break_separators-before_docked.ml.err b/test/passing/tests/break_separators-before_docked.ml.err
@@ -1 +0,0 @@
-Warning: tests/break_separators.ml:324 exceeds the margin

diff --git a/test/passing/tests/break_separators-before_docked.ml.ref b/test/passing/tests/break_separators-before_docked.ml.ref
@@ -322,7 +322,8 @@ let foooooooooooo =
 let foooooooooooo =
   {
     foooooooooooooo with
-    (* foooooooooooooooo fooooooooooooooooooooooooo foooooooooooooooooooooo *)
+    (* foooooooooooooooo fooooooooooooooooooooooooo foooooooooooooooooooooo
+    *)
     fooooooooooooooooooooooooooooo= fooooooooooooo
   ; fooooooooooooo= foooooooooooooo
   }
@@ -430,6 +431,7 @@ let () =
   match x with
   | ( _
     , (* verrrrrrrrrrrrrrrrrrrrrrrry looooooooooooooooong line 1
-         veeeeeeeeeeeeeeeeeeeeeryyyy loooooooooooooooooong line 2 *)
+         veeeeeeeeeeeeeeeeeeeeeryyyy loooooooooooooooooong line 2
+      *)
       Some _ ) ->
       x
diff --git a/test/passing/tests/break_separators.ml b/test/passing/tests/break_separators.ml
@@ -287,7 +287,8 @@ let foooooooooooo =
 
 let foooooooooooo =
   { foooooooooooooo with
-    (* foooooooooooooooo fooooooooooooooooooooooooo foooooooooooooooooooooo *)
+    (* foooooooooooooooo fooooooooooooooooooooooooo foooooooooooooooooooooo
+    *)
     fooooooooooooooooooooooooooooo= fooooooooooooo
   ; fooooooooooooo= foooooooooooooo }
 
@@ -381,6 +382,7 @@ let () =
   match x with
   | ( _
     , (* verrrrrrrrrrrrrrrrrrrrrrrry looooooooooooooooong line 1
-         veeeeeeeeeeeeeeeeeeeeeryyyy loooooooooooooooooong line 2 *)
+         veeeeeeeeeeeeeeeeeeeeeryyyy loooooooooooooooooong line 2
+      *)
       Some _ ) ->
       x
diff --git a/test/passing/tests/break_separators.ml.err b/test/passing/tests/break_separators.ml.err
@@ -1 +0,0 @@
-Warning: tests/break_separators.ml:289 exceeds the margin

diff --git a/test/passing/tests/doc_comments-no-wrap.mli.err b/test/passing/tests/doc_comments-no-wrap.mli.err
@@ -1,20 +1,15 @@
-Warning: tests/doc_comments.mli:10 exceeds the margin
-Warning: tests/doc_comments.mli:79 exceeds the margin
-Warning: tests/doc_comments.mli:83 exceeds the margin
-Warning: tests/doc_comments.mli:87 exceeds the margin
-Warning: tests/doc_comments.mli:92 exceeds the margin
-Warning: tests/doc_comments.mli:96 exceeds the margin
-Warning: tests/doc_comments.mli:110 exceeds the margin
-Warning: tests/doc_comments.mli:115 exceeds the margin
-Warning: tests/doc_comments.mli:124 exceeds the margin
-Warning: tests/doc_comments.mli:328 exceeds the margin
-Warning: tests/doc_comments.mli:377 exceeds the margin
-Warning: tests/doc_comments.mli:384 exceeds the margin
-Warning: tests/doc_comments.mli:451 exceeds the margin
-Warning: tests/doc_comments.mli:465 exceeds the margin
-Warning: tests/doc_comments.mli:522 exceeds the margin
-Warning: tests/doc_comments.mli:552 exceeds the margin
-Warning: tests/doc_comments.mli:622 exceeds the margin
-Warning: tests/doc_comments.mli:624 exceeds the margin
-Warning: tests/doc_comments.mli:645 exceeds the margin
-Warning: tests/doc_comments.mli:658 exceeds the margin
+Warning: tests/doc_comments.mli:80 exceeds the margin
+Warning: tests/doc_comments.mli:84 exceeds the margin
+Warning: tests/doc_comments.mli:88 exceeds the margin
+Warning: tests/doc_comments.mli:93 exceeds the margin
+Warning: tests/doc_comments.mli:97 exceeds the margin
+Warning: tests/doc_comments.mli:111 exceeds the margin
+Warning: tests/doc_comments.mli:116 exceeds the margin
+Warning: tests/doc_comments.mli:125 exceeds the margin
+Warning: tests/doc_comments.mli:330 exceeds the margin
+Warning: tests/doc_comments.mli:387 exceeds the margin
+Warning: tests/doc_comments.mli:559 exceeds the margin
+Warning: tests/doc_comments.mli:629 exceeds the margin
+Warning: tests/doc_comments.mli:631 exceeds the margin
+Warning: tests/doc_comments.mli:652 exceeds the margin
+Warning: tests/doc_comments.mli:665 exceeds the margin
diff --git a/test/passing/tests/doc_comments-no-wrap.mli.ref b/test/passing/tests/doc_comments-no-wrap.mli.ref
@@ -8,7 +8,8 @@ type block =
   | `Noblank
   | `Blocks of block list ]
 
-(** Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod *)
+(** Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+*)
 include M with type t := t
 
 val escape : string -> string
@@ -122,7 +123,8 @@ val k : k
 
     @canonical foo
 
-    @canonical Foooooooooooooooooooooooooooooooooooo.Baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaar *)
+    @canonical Foooooooooooooooooooooooooooooooooooo.Baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaar
+*)
 
 val x : x
 (** a comment
@@ -375,14 +377,16 @@ end
 
     @canonical Foo.Bar *)
 
-(** {%html:<p>Raw markup</p>%} {%Without language%} {%other:Other language%} *)
+(** {%html:<p>Raw markup</p>%} {%Without language%} {%other:Other language%}
+*)
 
 (** [Multi
      Line]
 
     [ A lot of    spaces ]
 
-    [Very looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong] *)
+    [Very looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong]
+*)
 
 (** {[
       for i = 1 to 3 do
@@ -449,7 +453,8 @@ end
 
 (** This is a comment with code inside
     {[
-      (** This is a comment with code inside [ let code inside = f inside ] *)
+      (** This is a comment with code inside [ let code inside = f inside ]
+      *)
       let code inside (* comment   *) = f inside
     ]}
 
@@ -463,7 +468,8 @@ end
     ]}
 
     {@ocaml kind=toplevel env=e1[
-      (** This is a comment with code inside [ let code inside = f inside ] *)
+      (** This is a comment with code inside [ let code inside = f inside ]
+      *)
       let code inside (* comment   *) = f inside
     ]} *)
 
@@ -520,7 +526,8 @@ val k : int
 
 (** Brackets must not be escaped in the first argument of some tags: *)
 
-(** @raise [Invalid_argument] if the argument is [None]. Sometimes [t.[x]]. *)
+(** @raise [Invalid_argument] if the argument is [None]. Sometimes [t.[x]].
+*)
 
 (** @author [Abc] [def] \[hij\] *)
 

diff --git a/test/passing/tests/doc_comments.mli.err b/test/passing/tests/doc_comments.mli.err
@@ -1,20 +1,15 @@
-Warning: tests/doc_comments.mli:10 exceeds the margin
-Warning: tests/doc_comments.mli:79 exceeds the margin
-Warning: tests/doc_comments.mli:83 exceeds the margin
-Warning: tests/doc_comments.mli:87 exceeds the margin
-Warning: tests/doc_comments.mli:92 exceeds the margin
-Warning: tests/doc_comments.mli:96 exceeds the margin
-Warning: tests/doc_comments.mli:110 exceeds the margin
-Warning: tests/doc_comments.mli:115 exceeds the margin
-Warning: tests/doc_comments.mli:124 exceeds the margin
-Warning: tests/doc_comments.mli:328 exceeds the margin
-Warning: tests/doc_comments.mli:377 exceeds the margin
-Warning: tests/doc_comments.mli:384 exceeds the margin
-Warning: tests/doc_comments.mli:451 exceeds the margin
-Warning: tests/doc_comments.mli:465 exceeds the margin
-Warning: tests/doc_comments.mli:522 exceeds the margin
-Warning: tests/doc_comments.mli:552 exceeds the margin
-Warning: tests/doc_comments.mli:616 exceeds the margin
-Warning: tests/doc_comments.mli:618 exceeds the margin
-Warning: tests/doc_comments.mli:639 exceeds the margin
-Warning: tests/doc_comments.mli:652 exceeds the margin
+Warning: tests/doc_comments.mli:80 exceeds the margin
+Warning: tests/doc_comments.mli:84 exceeds the margin
+Warning: tests/doc_comments.mli:88 exceeds the margin
+Warning: tests/doc_comments.mli:93 exceeds the margin
+Warning: tests/doc_comments.mli:97 exceeds the margin
+Warning: tests/doc_comments.mli:111 exceeds the margin
+Warning: tests/doc_comments.mli:116 exceeds the margin
+Warning: tests/doc_comments.mli:125 exceeds the margin
+Warning: tests/doc_comments.mli:330 exceeds the margin
+Warning: tests/doc_comments.mli:387 exceeds the margin
+Warning: tests/doc_comments.mli:559 exceeds the margin
+Warning: tests/doc_comments.mli:623 exceeds the margin
+Warning: tests/doc_comments.mli:625 exceeds the margin
+Warning: tests/doc_comments.mli:646 exceeds the margin
+Warning: tests/doc_comments.mli:659 exceeds the margin
diff --git a/test/passing/tests/doc_comments.mli.ref b/test/passing/tests/doc_comments.mli.ref
@@ -8,7 +8,8 @@ type block =
   | `Noblank
   | `Blocks of block list ]
 
-(** Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod *)
+(** Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+*)
 include M with type t := t
 
 val escape : string -> string
@@ -122,7 +123,8 @@ val k : k
 
     @canonical foo
 
-    @canonical Foooooooooooooooooooooooooooooooooooo.Baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaar *)
+    @canonical Foooooooooooooooooooooooooooooooooooo.Baaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaar
+*)
 
 val x : x
 (** a comment
@@ -375,14 +377,16 @@ end
 
     @canonical Foo.Bar *)
 
-(** {%html:<p>Raw markup</p>%} {%Without language%} {%other:Other language%} *)
+(** {%html:<p>Raw markup</p>%} {%Without language%} {%other:Other language%}
+*)
 
 (** [Multi
      Line]
 
     [ A lot of    spaces ]
 
-    [Very looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong] *)
+    [Very looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong]
+*)
 
 (** {[
       for i = 1 to 3 do
@@ -449,7 +453,8 @@ end
 
 (** This is a comment with code inside
     {[
-      (** This is a comment with code inside [ let code inside = f inside ] *)
+      (** This is a comment with code inside [ let code inside = f inside ]
+      *)
       let code inside (* comment *) = f inside
     ]}
 
@@ -463,7 +468,8 @@ end
     ]}
 
     {@ocaml kind=toplevel env=e1[
-      (** This is a comment with code inside [ let code inside = f inside ] *)
+      (** This is a comment with code inside [ let code inside = f inside ]
+      *)
       let code inside (* comment *) = f inside
     ]} *)
 
@@ -520,7 +526,8 @@ val k : int
 
 (** Brackets must not be escaped in the first argument of some tags: *)
 
-(** @raise [Invalid_argument] if the argument is [None]. Sometimes [t.[x]]. *)
+(** @raise [Invalid_argument] if the argument is [None]. Sometimes [t.[x]].
+*)
 
 (** @author [Abc] [def] \[hij\] *)
 

diff --git a/test/passing/tests/js_sig.mli.ref b/test/passing/tests/js_sig.mli.ref
@@ -9,7 +9,8 @@ exception Second_exception
 [@@@ocamlformat "parse-docstrings=true"]
 [@@@ocamlformat "wrap-comments=true"]
 
-(** {e foooooooo oooooo oooo oooo ooooo oooo ooooo} {i fooooo ooooo ooo oooooo oo oooooo oooo} {b fooooooo oooooo oooooo oooooo oooooo ooooooo} *)
+(** {e foooooooo oooooo oooo oooo ooooo oooo ooooo} {i fooooo ooooo ooo oooooo oo oooooo oooo} {b fooooooo oooooo oooooo oooooo oooooo ooooooo}
+*)
 
 (** {e foooooooo oooooooooo ooooooooo ooooooooo} {{!some ref} fooooooooooooo
     oooooooo oooooooooo} {b fooooooooooooo oooooooooooo oooooo ooooooo} *)

diff --git a/test/passing/tests/ocp_indent_compat-break_colon_after.ml.ref b/test/passing/tests/ocp_indent_compat-break_colon_after.ml.ref
@@ -16,7 +16,8 @@ module type M = sig
 
   val transl_modtype_longident
     (* foooooooooo fooooooooooooo foooooooooooo foooooooooooooo
-       foooooooooooooo foooooooooooo *) :
+       foooooooooooooo foooooooooooo
+    *) :
     (Location.t -> Env.t -> Longident.t -> Path.t) ref
 
   val imported_sets_of_closures_table :

diff --git a/test/passing/tests/ocp_indent_compat.ml b/test/passing/tests/ocp_indent_compat.ml
@@ -16,7 +16,8 @@ module type M = sig
 
   val transl_modtype_longident
     (* foooooooooo fooooooooooooo foooooooooooo foooooooooooooo
-       foooooooooooooo foooooooooooo *)
+       foooooooooooooo foooooooooooo
+    *)
     : (Location.t -> Env.t -> Longident.t -> Path.t) ref
 
   val imported_sets_of_closures_table