Merge doc-comments-val with doc-comments, new value before-except-val…

…; after becomes after-when-possible (#1358)
ocaml-ppx · May 11, 2020 · 403e020 · 403e020
1 parent 0e46fb2
commit 403e020
Show file tree

Hide file tree

Showing 15 changed files with 121 additions and 43 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -2,9 +2,20 @@
 
 #### Changes
 
-  + Set `doc-comments-val` to `unset` by default (#1340) (Jules Aguillon)
-    Placement of documentation comments on `val` and `external` items is now
-    controled by `doc-comments` unless this option is set.
+  + Merge `doc-comments-val` option with `doc-comments`. The placement of documentation comments on `val` and `external` items is now controled by `doc-comments`.
+
+    - `doc-comments=after` becomes `doc-comments=after-when-possible` to take into account the technical limitations of ocamlformat;
+    - `doc-comments=before` is unchanged;
+    - `doc-comments-val` is now replaced with `doc-comments`
+      To reproduce the former behaviors
+      * `doc-comments=before` + `doc-comments-val=before`: now use `doc-comments=before`;
+      * `doc-comments=before` + `doc-comments-val=after`: now use `doc-comments=before-except-val`;
+      * `doc-comments=after` + `doc-comments-val=before`: this behavior did not make much sense and is not available anymore;
+      * `doc-comments=after` + `doc-comments-val=after`: now use `doc-comments=after-when-possible`.
+
+   (#1358) (Josh Berdine, Jules Aguillon, Guillaume Petiot)
+
+   This reverts changes introduced in 0.14.1 (#1335) and 0.14.0 (#1012).
 
 ### 0.14.1 (2020-04-14)
 

diff --git a/lib/Conf.ml b/lib/Conf.ml
@@ -32,7 +32,7 @@ type t =
   ; comment_check: bool
   ; disable: bool
   ; disambiguate_non_breaking_match: bool
-  ; doc_comments: [`Before | `After]
+  ; doc_comments: [`Before | `Before_except_val | `After_when_possible]
   ; doc_comments_val: [`Before | `After | `Unset]
   ; doc_comments_padding: int
   ; doc_comments_tag_only: [`Fit | `Default]
@@ -484,24 +484,37 @@ module Formatting = struct
     let doc = "Doc comments position." in
     let names = ["doc-comments"] in
     let all =
-      [ ( "after"
-        , `After
-        , "$(b,after) puts doc comments after the corresponding code. This \
-           option has no effect on variant declarations because that would \
-           change their meaning and on structures, signatures and objects \
-           for readability." )
+      [ ( "after-when-possible"
+        , `After_when_possible
+        , "$(b,after-when-possible) puts doc comments after the \
+           corresponding code. This option has no effect on variant \
+           declarations because that would change their meaning and on \
+           structures, signatures and objects for readability." )
+      ; ( "before-except-val"
+        , `Before_except_val
+        , "$(b,before-except-val) puts doc comments before the \
+           corresponding code, but puts doc comments of $(b,val) and \
+           $(b,external) declarations after the corresponding declarations."
+        )
       ; ( "before"
         , `Before
         , "$(b,before) puts comments before the corresponding code." ) ]
     in
     C.choice ~names ~all ~doc ~section
+      ~removed_values:
+        [ C.removed_value ~name:"after" ~version:"0.14.2"
+            ~msg:
+              "This value has been renamed `after-when-possible` to take \
+               into account the technical limitations of ocamlformat, the \
+               behavior is unchanged." ]
       (fun conf x -> {conf with doc_comments= x})
       (fun conf -> conf.doc_comments)
 
   let doc_comments_val =
     let doc =
       "Documentation comments position on $(b,val) and $(b,external) \
-       declarations."
+       declarations. $(b,Warning:) this option is $(b,deprecated) and will \
+       be removed in OCamlFormat v0.15.0."
     in
     let names = ["doc-comments-val"] in
     let all =
@@ -514,7 +527,45 @@ module Formatting = struct
            declarations." )
       ; ("before", `Before, "$(b,before) puts them before.") ]
     in
-    C.choice ~names ~all ~doc ~section
+    let deprecated =
+      C.deprecated ~since_version:"0.14.2"
+        "$(b,Warning:) this option is $(b,deprecated) and will be removed \
+         in OCamlFormat v0.15.0, please use `doc-comments` instead. If you \
+         are using `doc-comments-val=before` in combination with \
+         `doc-comments=before` then only `doc-comments=before` is now \
+         required to achive the same behavior. If you are using \
+         `doc-comments-val=before` in combination with `doc-comments=after` \
+         this behavior is not available anymore. If you are using \
+         `doc-comments-val=after` in combination with `doc-comments=before` \
+         please now use `doc-comments=before-except-val`. If you are using \
+         `doc-comments-val=after` in combination with `doc-comments=after` \
+         then only `doc-comments=after-when-possible` is now required to \
+         achieve the same behavior. If you are using \
+         `doc-comments-val=unset` the same behavior can now be achieved by \
+         setting `doc-comments` only."
+    in
+    C.choice ~names ~all ~doc ~section ~deprecated
+      ~removed_values:
+        [ C.removed_value ~name:"before" ~version:"0.14.2"
+            ~msg:
+              "If you are using `doc-comments-val=before` in combination \
+               with `doc-comments=before` then only `doc-comments=before` \
+               is now required to achive the same behavior. If you are \
+               using `doc-comments-val=before` in combination with \
+               `doc-comments=after` this behavior is not available anymore."
+        ; C.removed_value ~name:"after" ~version:"0.14.2"
+            ~msg:
+              "If you are using `doc-comments-val=after` in combination \
+               with `doc-comments=before` please now use \
+               `doc-comments=before-except-val`. If you are using \
+               `doc-comments-val=after` in combination with \
+               `doc-comments=after` then only \
+               `doc-comments=after-when-possible` is now required to \
+               achieve the same behavior."
+        ; C.removed_value ~name:"unset" ~version:"0.14.2"
+            ~msg:
+              "The same behavior can be achieved by setting `doc-comments` \
+               only." ]
       (fun conf x -> {conf with doc_comments_val= x})
       (fun conf -> conf.doc_comments_val)
 
@@ -1459,8 +1510,8 @@ let ocamlformat_profile =
   ; comment_check= true
   ; disable= false
   ; disambiguate_non_breaking_match= false
-  ; doc_comments= `Before
-  ; doc_comments_val= `After
+  ; doc_comments= `Before_except_val
+  ; doc_comments_val= `Unset
   ; doc_comments_padding= 2
   ; doc_comments_tag_only= `Default
   ; dock_collection_brackets= false

diff --git a/lib/Conf.mli b/lib/Conf.mli
@@ -34,7 +34,7 @@ type t =
   ; comment_check: bool
   ; disable: bool
   ; disambiguate_non_breaking_match: bool
-  ; doc_comments: [`Before | `After]
+  ; doc_comments: [`Before | `Before_except_val | `After_when_possible]
   ; doc_comments_val: [`Before | `After | `Unset]
   ; doc_comments_padding: int
   ; doc_comments_tag_only: [`Fit | `Default]

diff --git a/lib/Fmt_ast.ml b/lib/Fmt_ast.ml
@@ -465,11 +465,11 @@ let fmt_docstring_around_item' ?(is_val = false) ?(force_before = false)
         then `Fit
         else
           let ((`Before | `After) as conf) =
-            if is_val then
-              match c.conf.doc_comments_val with
-              | (`Before | `After) as conf -> conf
-              | `Unset -> c.conf.doc_comments
-            else c.conf.doc_comments
+            match c.conf.doc_comments with
+            | `After_when_possible -> `After
+            | `Before_except_val when is_val -> `After
+            | `Before_except_val -> `Before
+            | `Before -> `Before
           in
           conf
       in

diff --git a/ocamlformat-help.txt b/ocamlformat-help.txt
@@ -155,13 +155,15 @@ OPTIONS (CODE FORMATTING STYLE)
            Add parentheses around matching constructs that fit on a single
            line. The flag is unset by default.
 
-       --doc-comments={after|before}
-           Doc comments position. after puts doc comments after the
-           corresponding code. This option has no effect on variant
+       --doc-comments={after-when-possible|before-except-val|before}
+           Doc comments position. after-when-possible puts doc comments after
+           the corresponding code. This option has no effect on variant
            declarations because that would change their meaning and on
-           structures, signatures and objects for readability. before puts
-           comments before the corresponding code. The default value is
-           after.
+           structures, signatures and objects for readability.
+           before-except-val puts doc comments before the corresponding code,
+           but puts doc comments of val and external declarations after the
+           corresponding declarations. before puts comments before the
+           corresponding code. The default value is after-when-possible.
 
        --doc-comments-padding=PADDING
            Add PADDING spaces before doc comments in type declarations. The
@@ -174,9 +176,25 @@ OPTIONS (CODE FORMATTING STYLE)
 
        --doc-comments-val={unset|after|before}
            Documentation comments position on val and external declarations.
-           unset lets doc-comments set the position. after puts documentation
-           comments after their corresponding declarations. before puts them
-           before. The default value is unset.
+           Warning: this option is deprecated and will be removed in
+           OCamlFormat v0.15.0. unset lets doc-comments set the position.
+           after puts documentation comments after their corresponding
+           declarations. before puts them before. The default value is unset.
+           Warning: This option is deprecated since version 0.14.2. Warning:
+           this option is deprecated and will be removed in OCamlFormat
+           v0.15.0, please use `doc-comments` instead. If you are using
+           `doc-comments-val=before` in combination with
+           `doc-comments=before` then only `doc-comments=before` is now
+           required to achive the same behavior. If you are using
+           `doc-comments-val=before` in combination with `doc-comments=after`
+           this behavior is not available anymore. If you are using
+           `doc-comments-val=after` in combination with `doc-comments=before`
+           please now use `doc-comments=before-except-val`. If you are using
+           `doc-comments-val=after` in combination with `doc-comments=after`
+           then only `doc-comments=after-when-possible` is now required to
+           achieve the same behavior. If you are using
+           `doc-comments-val=unset` the same behavior can now be achieved by
+           setting `doc-comments` only.
 
        --dock-collection-brackets
            Dock the brackets of lists, arrays and records, so that when the

diff --git a/test/passing/doc_comments-after.ml.opts b/test/passing/doc_comments-after.ml.opts
@@ -1 +1 @@
---doc-comments=after
+--doc-comments=after-when-possible
diff --git a/...mments-val-after.ml.minimum-ocaml-version → ...efore-except-val.ml.minimum-ocaml-version b/...mments-val-after.ml.minimum-ocaml-version → ...efore-except-val.ml.minimum-ocaml-version
diff --git a/test/passing/doc_comments-before-except-val.ml.opts b/test/passing/doc_comments-before-except-val.ml.opts
@@ -0,0 +1 @@
+--doc-comments=before-except-val
diff --git a/test/passing/doc_comments-val-after.ml.ref → ...ing/doc_comments-before-except-val.ml.ref b/test/passing/doc_comments-val-after.ml.ref → ...ing/doc_comments-before-except-val.ml.ref
diff --git a/test/passing/doc_comments-before.ml.opts b/test/passing/doc_comments-before.ml.opts
@@ -1,2 +1 @@
 --doc-comments=before
---doc-comments-val=before
diff --git a/test/passing/doc_comments-val-after.ml.opts b/test/passing/doc_comments-val-after.ml.opts
diff --git a/test/passing/dune.inc b/test/passing/dune.inc
@@ -665,28 +665,28 @@
  (action (diff doc_comments-after.ml.ref doc_comments-after.ml.output)))
 
 (rule
- (targets doc_comments-before.ml.output)
+ (targets doc_comments-before-except-val.ml.output)
  (deps .ocamlformat )
  (action
    (with-outputs-to %{targets}
-     (system "%{bin:ocamlformat} %{read-lines:doc_comments-before.ml.opts} %{dep:doc_comments.ml}"))))
+     (system "%{bin:ocamlformat} %{read-lines:doc_comments-before-except-val.ml.opts} %{dep:doc_comments.ml}"))))
 
 (alias
  (name runtest)
  (enabled_if (>= %{ocaml_version} 4.08.0))
- (action (diff doc_comments-before.ml.ref doc_comments-before.ml.output)))
+ (action (diff doc_comments-before-except-val.ml.ref doc_comments-before-except-val.ml.output)))
 
 (rule
- (targets doc_comments-val-after.ml.output)
+ (targets doc_comments-before.ml.output)
  (deps .ocamlformat )
  (action
    (with-outputs-to %{targets}
-     (system "%{bin:ocamlformat} %{read-lines:doc_comments-val-after.ml.opts} %{dep:doc_comments.ml}"))))
+     (system "%{bin:ocamlformat} %{read-lines:doc_comments-before.ml.opts} %{dep:doc_comments.ml}"))))
 
 (alias
  (name runtest)
  (enabled_if (>= %{ocaml_version} 4.08.0))
- (action (diff doc_comments-val-after.ml.ref doc_comments-val-after.ml.output)))
+ (action (diff doc_comments-before.ml.ref doc_comments-before.ml.output)))
 
 (rule
  (targets doc_comments.ml.output)

diff --git a/test/passing/print_config.ml.ref b/test/passing/print_config.ml.ref
@@ -47,8 +47,8 @@ escape-chars=preserve (profile ocamlformat (file .ocamlformat:1))
 dock-collection-brackets=false (profile ocamlformat (file .ocamlformat:1))
 doc-comments-tag-only=default (profile ocamlformat (file .ocamlformat:1))
 doc-comments-padding=2 (profile ocamlformat (file .ocamlformat:1))
-doc-comments-val=after (profile ocamlformat (file .ocamlformat:1))
-doc-comments=before (profile ocamlformat (file .ocamlformat:1))
+doc-comments-val=unset (profile ocamlformat (file .ocamlformat:1))
+doc-comments=before-except-val (profile ocamlformat (file .ocamlformat:1))
 disambiguate-non-breaking-match=false (profile ocamlformat (file .ocamlformat:1))
 disable=false (profile ocamlformat (file .ocamlformat:1))
 cases-matching-exp-indent=compact (profile ocamlformat (file .ocamlformat:1))

diff --git a/test/passing/verbose1.ml.ref b/test/passing/verbose1.ml.ref
@@ -47,7 +47,7 @@ escape-chars=preserve (profile ocamlformat (file .ocamlformat:1))
 dock-collection-brackets=false (profile ocamlformat (file .ocamlformat:1))
 doc-comments-tag-only=default (profile ocamlformat (file .ocamlformat:1))
 doc-comments-padding=2 (profile ocamlformat (file .ocamlformat:1))
-doc-comments-val=after (profile ocamlformat (file .ocamlformat:1))
+doc-comments-val=unset (profile ocamlformat (file .ocamlformat:1))
 doc-comments=before (command line)
 disambiguate-non-breaking-match=false (profile ocamlformat (file .ocamlformat:1))
 disable=false (profile ocamlformat (file .ocamlformat:1))

diff --git a/test/passing/verbose2.ml.ref b/test/passing/verbose2.ml.ref
@@ -47,7 +47,7 @@ escape-chars=preserve (profile ocamlformat (file .ocamlformat:1))
 dock-collection-brackets=false (profile ocamlformat (file .ocamlformat:1))
 doc-comments-tag-only=default (profile ocamlformat (file .ocamlformat:1))
 doc-comments-padding=2 (profile ocamlformat (file .ocamlformat:1))
-doc-comments-val=after (profile ocamlformat (file .ocamlformat:1))
+doc-comments-val=unset (profile ocamlformat (file .ocamlformat:1))
 doc-comments=before (command line)
 disambiguate-non-breaking-match=false (profile ocamlformat (file .ocamlformat:1))
 disable=false (profile ocamlformat (file .ocamlformat:1))