Do not consider leading star '*' when checking the diff of doc comments (#1712)

Fixup #1695

Author: hhugo

CHANGES.md

@@ -34,13 +34,12 @@
 
   + Fix parentheses around successive unary operations (#1696, @gpetiot)
 
-  + Fix normalization of odoc paragraphs (#1695, @gpetiot)
-    Paragraphs must not be considered for the normalized form. They are only structural and the shape of a docstring organized in paragraphs only depend on linebreaks, which may be changed by the formatting.
-
   + Add missing break between pattern and attribute (#1711, @gpetiot)
 
   + Add missing parentheses around expression having attributes or comments inside a shorthand let-open clause (#1708, @gpetiot)
 
+  + Do not consider leading star '*' when checking the diff of doc comments (#1712, @hhugo)
+
 #### Changes
 
   + Improve the diff of unstable docstrings displayed in error messages (#1654, @gpetiot)

dune-project

@@ -47,7 +47,6 @@
   base-unix
   cmdliner
   dune-build-info
-  either
   fix
   fpath
   (menhir
@@ -90,7 +89,6 @@
   base-unix
   cmdliner
   dune-build-info
-  either
   fix
   fpath
   (menhir

lib/Normalize.ml

@@ -93,12 +93,7 @@ and odoc_inline_elements fmt elems =
   list (ign_loc odoc_inline_element) fmt elems
 
 let rec odoc_nestable_block_element c fmt = function
-  | `Paragraph elms ->
-      (* Paragraphs must not be considered for the normalized form. They are
-         only structural and the shape of a docstring organized in paragraphs
-         only depend on linebreaks, which may be changed by the
-         formatting. *)
-      odoc_inline_elements fmt elms
+  | `Paragraph elms -> fpf fmt "Paragraph(%a)" odoc_inline_elements elms
   | `Code_block (_, txt) ->
       let txt = Odoc_parser.Loc.value txt in
       let txt =

lib/Translation_unit.ml

@@ -353,14 +353,24 @@ let format (type a b) (fg0 : a Ast_passes.Ast0.t)
         ( match Cmts.remaining_comments cmts_t with
         | [] -> ()
         | l -> internal_error (`Comment_dropped l) [] ) ;
-        let is_docstring Cmt.{txt; _} =
-          conf.parse_docstrings && Char.equal txt.[0] '*'
+        let is_docstring (Cmt.{txt; loc} as cmt) =
+          match txt with
+          | "" | "*" -> Either.Second cmt
+          | _ when Char.equal txt.[0] '*' ->
+              (* Doc comments here (comming directly from the lexer) include
+                 their leading star *. It is not part of the docstring and
+                 should be dropped. *)
+              let txt = String.drop_prefix txt 1 in
+              let cmt = Cmt.create txt loc in
+              if conf.parse_docstrings then Either.First cmt
+              else Either.Second cmt
+          | _ -> Either.Second cmt
         in
         let old_docstrings, old_comments =
-          List.partition_tf t.comments ~f:is_docstring
+          List.partition_map t.comments ~f:is_docstring
         in
         let t_newdocstrings, t_newcomments =
-          List.partition_tf t_new.comments ~f:is_docstring
+          List.partition_map t_new.comments ~f:is_docstring
         in
         let diff_cmts =
           Sequence.append

ocamlformat-rpc.opam

@@ -18,7 +18,6 @@ depends: [
   "base-unix"
   "cmdliner"
   "dune-build-info"
-  "either"
   "fix"
   "fpath"
   "menhir" {>= "20180528"}

ocamlformat.opam

@@ -17,7 +17,6 @@ depends: [
   "base-unix"
   "cmdliner"
   "dune-build-info"
-  "either"
   "fix"
   "fpath"
   "menhir" {>= "20180528"}

test/passing/dune.inc

@@ -755,6 +755,18 @@
  (package ocamlformat)
  (action (diff tests/doc_comments-before.ml.ref doc_comments-before.ml.output)))
 
+(rule
+ (deps tests/.ocamlformat )
+ (package ocamlformat)
+ (action
+   (with-outputs-to doc_comments-parse-docstrings.mli.output
+     (run %{bin:ocamlformat} --parse-docstrings %{dep:tests/doc_comments.mli}))))
+
+(rule
+ (alias runtest)
+ (package ocamlformat)
+ (action (diff tests/doc_comments-parse-docstrings.mli.ref doc_comments-parse-docstrings.mli.output)))
+
 (rule
  (deps tests/.ocamlformat )
  (package ocamlformat)

test/passing/tests/doc_comments-parse-docstrings.mli.opts

@@ -0,0 +1 @@
+--parse-docstrings