Set 'doc-comments = before' in profile 'ocamlformat' (#1325)

* Set 'doc-comments = before' in profile 'ocamlformat'

This option is now deprecated, the value currently used by the ocamlformat profile will be removed.

This is already done for the conventional profile, the new `doc-comments-val = after` option (set by default) minimizes the diffs.

Author: Julow

CHANGES.md

@@ -17,8 +17,9 @@
   + Add the option `doc-comments-val=before|after` (#1012) (Jules Aguillon)
     This option set the placement of documentation comment on `val` and `external` only.
     It is set to `after` by default.
-    The default for `doc-comments` is changed from `after` to `before`, this
-    option will be deleted in the future.
+
+  + The default for `doc-comments` is changed from `after` to `before` (#1012, #1325) (Jules Aguillon)
+    This affects both `conventional` (default) and `ocamlformat` profiles.
 
   + Some options are now deprecated:
     * `doc-comments` (#1293, #1012)

lib/Ast.mli

@@ -157,9 +157,9 @@ val assoc_of_prec : prec -> assoc
 (** [assoc_of_prec prec] is the associativity of Ast terms with precedence
     [prec]. (Associativity is uniform across precedence levels.) *)
 
-type 'a xt = private {ctx: t; ast: 'a}
 (** Term-in-context [{ctx; ast}] records that [ast] is (considered to be) an
     immediate sub-term of [ctx]. *)
+type 'a xt = private {ctx: t; ast: 'a}
 
 val sub_typ : ctx:t -> core_type -> core_type xt
 (** Construct a core_type-in-context. *)

lib/Conf.ml

@@ -1461,7 +1461,7 @@ let ocamlformat_profile =
   ; comment_check= true
   ; disable= false
   ; disambiguate_non_breaking_match= false
-  ; doc_comments= `After
+  ; doc_comments= `Before
   ; doc_comments_val= `After
   ; doc_comments_padding= 2
   ; doc_comments_tag_only= `Default

lib/Conf.mli

@@ -11,6 +11,7 @@
 
 (** Configuration options *)
 
+(** Formatting options *)
 type t =
   { align_cases: bool
   ; align_constructors_decl: bool
@@ -86,7 +87,6 @@ type t =
   ; type_decl_indent: int
   ; wrap_comments: bool  (** Wrap comments at margin. *)
   ; wrap_fun_args: bool }
-(** Formatting options *)
 
 type file = Stdin | File of string
 
@@ -102,12 +102,12 @@ type action =
       (** Check whether the input files already are formatted. *)
   | Print_config of t  (** Print the configuration and exit. *)
 
+(** Options changing the tool's behavior *)
 type opts =
   { debug: bool  (** Generate debugging output if true. *)
   ; margin_check: bool
         (** Check whether the formatted output exceeds the margin. *)
   ; format_invalid_files: bool }
-(** Options changing the tool's behavior *)
 
 val action : unit -> (action * opts) Cmdliner.Term.result
 (** Formatting action: input type and source, and output destination. *)

lib/Config_option.mli

@@ -42,9 +42,9 @@ module Make (C : CONFIG) : sig
 
   val deprecated : since_version:string -> string -> deprecated
 
-  type removed_value
   (** Indicate that a configuration value has been removed in an ocamlformat
       release. A message indicating how to migrate will be displayed. *)
+  type removed_value
 
   val removed_value :
     name:string -> version:string -> msg:string -> removed_value

lib/Fmt.mli

@@ -13,11 +13,11 @@
 
 module Format = Format_
 
-type s = (unit, Format.formatter, unit) format
 (** Format strings that accept no arguments. *)
+type s = (unit, Format.formatter, unit) format
 
-type t
 (** Format thunks. *)
+type t
 
 val ( $ ) : t -> t -> t
 (** Format concatenation: [a $ b] formats [a], then [b]. *)

lib/Source.ml

@@ -10,8 +10,8 @@
  **********************************************************************)
 open Migrate_ast
 
-type t = string
 (** Concrete syntax. *)
+type t = string
 
 let create s = s
 

lib/Translation_unit.ml

@@ -14,6 +14,7 @@
 open Migrate_ast
 open Parse_with_comments
 
+(** Operations on translation units. *)
 type 'a t =
   { init_cmts: debug:bool -> Source.t -> 'a -> Cmt.t list -> Cmts.t
   ; fmt: debug:bool -> Source.t -> Cmts.t -> Conf.t -> 'a -> Fmt.t
@@ -32,7 +33,6 @@ type 'a t =
       -> Normalize.docstring_error list
   ; normalize: Conf.t -> 'a with_comments -> 'a
   ; printast: Format.formatter -> 'a -> unit }
-(** Operations on translation units. *)
 
 exception
   Internal_error of

lib/Translation_unit.mli

@@ -11,6 +11,7 @@
 
 open Parse_with_comments
 
+(** Operations on translation units. *)
 type 'a t =
   { init_cmts: debug:bool -> Source.t -> 'a -> Cmt.t list -> Cmts.t
   ; fmt: debug:bool -> Source.t -> Cmts.t -> Conf.t -> 'a -> Fmt.t
@@ -29,7 +30,6 @@ type 'a t =
       -> Normalize.docstring_error list
   ; normalize: Conf.t -> 'a with_comments -> 'a
   ; printast: Caml.Format.formatter -> 'a -> unit }
-(** Operations on translation units. *)
 
 type error
 

test/cli/stdin_and_intf.expected

@@ -1,4 +1,4 @@
 val x : string
 
-module X : S
 (** Make sure this file cannot be parsed as an impl file *)
+module X : S

test/passing/break_separators-after.ml.ref

@@ -97,9 +97,9 @@ type trace_mod_funs =
   {trace_mod: bool option; trace_funs: bool Map.M(String).t}
 
 module Fooooo = struct
-  type t = {fooooo: fooo; fooooo: fooooooo}
   (** This is a long docstring so that it cannot be on the same line as the
       record type. *)
+  type t = {fooooo: fooo; fooooo: fooooooo}
 
   val select :
     (* The fsevents context *)

test/passing/break_separators-after_docked.ml.ref

@@ -110,9 +110,9 @@ type trace_mod_funs = {
 }
 
 module Fooooo = struct
-  type t = {fooooo: fooo; fooooo: fooooooo}
   (** This is a long docstring so that it cannot be on the same line as the
       record type. *)
+  type t = {fooooo: fooo; fooooo: fooooooo}
 
   val select :
     (* The fsevents context *)

test/passing/break_separators-after_docked_wrap.ml.ref

@@ -108,9 +108,9 @@ type trace_mod_funs = {
 }
 
 module Fooooo = struct
-  type t = {fooooo: fooo; fooooo: fooooooo}
   (** This is a long docstring so that it cannot be on the same line as the
       record type. *)
+  type t = {fooooo: fooo; fooooo: fooooooo}
 
   val select :
     (* The fsevents context *)

test/passing/break_separators-after_wrap.ml.ref

@@ -95,9 +95,9 @@ type trace_mod_funs =
   {trace_mod: bool option; trace_funs: bool Map.M(String).t}
 
 module Fooooo = struct
-  type t = {fooooo: fooo; fooooo: fooooooo}
   (** This is a long docstring so that it cannot be on the same line as the
       record type. *)
+  type t = {fooooo: fooo; fooooo: fooooooo}
 
   val select :
     (* The fsevents context *)

test/passing/break_separators-before_docked.ml.ref

@@ -110,9 +110,9 @@ type trace_mod_funs = {
 }
 
 module Fooooo = struct
-  type t = {fooooo: fooo; fooooo: fooooooo}
   (** This is a long docstring so that it cannot be on the same line as the
       record type. *)
+  type t = {fooooo: fooo; fooooo: fooooooo}
 
   val select :
        (* The fsevents context *)

test/passing/break_separators-before_docked_wrap.ml.ref

@@ -108,9 +108,9 @@ type trace_mod_funs = {
 }
 
 module Fooooo = struct
-  type t = {fooooo: fooo; fooooo: fooooooo}
   (** This is a long docstring so that it cannot be on the same line as the
       record type. *)
+  type t = {fooooo: fooo; fooooo: fooooooo}
 
   val select :
        (* The fsevents context *)

test/passing/break_separators-wrap.ml.ref

@@ -95,9 +95,9 @@ type trace_mod_funs =
   {trace_mod: bool option; trace_funs: bool Map.M(String).t}
 
 module Fooooo = struct
-  type t = {fooooo: fooo; fooooo: fooooooo}
   (** This is a long docstring so that it cannot be on the same line as the
       record type. *)
+  type t = {fooooo: fooo; fooooo: fooooooo}
 
   val select :
        (* The fsevents context *)

test/passing/break_separators.ml

@@ -97,9 +97,9 @@ type trace_mod_funs =
   {trace_mod: bool option; trace_funs: bool Map.M(String).t}
 
 module Fooooo = struct
-  type t = {fooooo: fooo; fooooo: fooooooo}
   (** This is a long docstring so that it cannot be on the same line as the
       record type. *)
+  type t = {fooooo: fooo; fooooo: fooooooo}
 
   val select :
        (* The fsevents context *)

test/passing/comment_in_modules.ml.ref

@@ -12,9 +12,9 @@ module type M = sig
   (* comments *)
 end
 
+(** Xxxxxxx xxxxxxxx xx xxxxxxx xxxxxxxxxxxxx xxxxxxxxx xx xxxx *)
 module Mmmmmmmmmmmmmmmmmmmmmm =
   Aaaaaaaaaaaaaaaaaaaaaa.Bbbbbbbbbbbbbbbbbbbbbbbb
-(** Xxxxxxx xxxxxxxx xx xxxxxxx xxxxxxxxxxxxx xxxxxxxxx xx xxxx *)
 
 (** Xxxxxxx xxxxxxxx xx xxxxxxx xxxxxxxxxxxxx xxxxxxxxx xx xxxx *)
 module Fffffffffffffff (Yyyyyyyyyyyyyyy : Z.S) =