ocamlformat: Enable formatting of docstrings

.ocamlformat

@@ -1,4 +1,3 @@
 module-item-spacing=preserve
 version=0.27.0
 ocaml-version=4.02
-parse-docstrings=false

doc/examples/expansion.mli

@@ -1,7 +1,7 @@
 (** Examples of different features of Expansion *)
 
-(** For details on what each of the following examples is showing,
-see the explanations in the {{!page-features}Features page} *)
+(** For details on what each of the following examples is showing, see the
+    explanations in the {{!page-features}Features page} *)
 
 [@@@warning "-67"]
 module Simple : sig
@@ -23,7 +23,8 @@ module Aliases : sig
 end
 
 module ModuleTypeAliases : sig
-  (** Demonstrates that module types are not expanded if they're a simple path to another. *)
+  (** Demonstrates that module types are not expanded if they're a simple path
+      to another. *)
 
   module type A = sig
     type t
@@ -125,7 +126,8 @@ module DeepEquality : sig
 end
 
 module DeepEquality2 : sig
-  (** Demonstrates expansion involving an equation on a type in a submodule, but the submodule is already a simple signature *)
+  (** Demonstrates expansion involving an equation on a type in a submodule, but
+      the submodule is already a simple signature *)
 
   module type MODTYPE = sig
     module X : sig
@@ -172,7 +174,8 @@ module ModuleTypeOf : sig
 end
 
 module ModuleTypeOfComplications : sig
-  (** Demonstrates the interaction of [module type of] and destructive module substitution *)
+  (** Demonstrates the interaction of [module type of] and destructive module
+      substitution *)
 
   module type S = sig
     module X : sig

doc/examples/markup.mli

@@ -1,42 +1,41 @@
 (** Markup examples. *)
 
 (** The OCaml manual gives a
-{{:https://ocaml.org/manual/ocamldoc.html#ss:ocamldoc-placement}comprehensive example}
-of comment placement. This has been replicated in the module Foo below to
-show how this is rendered by [odoc]. *)
+    {{:https://ocaml.org/manual/ocamldoc.html#ss:ocamldoc-placement}comprehensive
+     example} of comment placement. This has been replicated in the module Foo
+    below to show how this is rendered by [odoc]. *)
 
 module type Foo = sig
-  (** The first special comment of the file is the comment associated
-    with the whole module.*)
+  (** The first special comment of the file is the comment associated with the
+      whole module.*)
 
-  (** Special comments can be placed between elements and are kept
-    by the OCamldoc tool, but are not associated to any element.
-    [@]-tags in these comments are ignored.*)
+  (** Special comments can be placed between elements and are kept by the
+      OCamldoc tool, but are not associated to any element. [@]-tags in these
+      comments are ignored.*)
 
   (*******************************************************************)
-  (** Comments like the one above, with more than two asterisks,
-    are ignored. *)
+  (** Comments like the one above, with more than two asterisks, are ignored. *)
 
   (** The comment for function f. *)
   val f : int -> int -> int
   (** The continuation of the comment for function f. *)
 
   (* Hello, I'm a simple comment :-) *)
   exception My_exception of (int -> int) * int
-  (** Comment for exception My_exception, even with a simple comment
-    between the special comment and the exception.*)
+  (** Comment for exception My_exception, even with a simple comment between the
+      special comment and the exception.*)
 
-  (** Comment for type weather  *)
+  (** Comment for type weather *)
   type weather =
     | Rain of int  (** The comment for constructor Rain *)
     | Sun  (** The comment for constructor Sun *)
 
-  (** Comment for type weather2  *)
+  (** Comment for type weather2 *)
   type weather2 =
     | Rain of int  (** The comment for constructor Rain *)
     | Sun  (** The comment for constructor Sun *)
-  (** I can continue the comment for type weather2 here
-  because there is already a comment associated to the last constructor.*)
+  (** I can continue the comment for type weather2 here because there is already
+      a comment associated to the last constructor.*)
 
   (** The comment for type my_record *)
   type my_record = {
@@ -67,9 +66,8 @@ module type Foo = sig
     val toto : int
     (** The comment for attribute toto. *)
 
-    (** This comment is not attached to titi since
-        there is a blank line before titi, but is kept
-        as a comment in the class. *)
+    (** This comment is not attached to titi since there is a blank line before
+        titi, but is kept as a comment in the class. *)
 
     val titi : string
 
@@ -126,8 +124,8 @@ module Stop : sig
   end
 
   val foo : string
-  (** This value appears in the documentation, since the Stop special comment
-      in the class does not affect the parent module of the class.*)
+  (** This value appears in the documentation, since the Stop special comment in
+      the class does not affect the parent module of the class.*)
 
   (**/**)
 
@@ -137,14 +135,14 @@ module Stop : sig
   (**/**)
 
   type t = string
-  (** The type t appears since in the documentation since the previous stop comment
-  toggled off the "no documentation mode". *)
+  (** The type t appears since in the documentation since the previous stop
+      comment toggled off the "no documentation mode". *)
 end
 
 (** {2 Scoping rules} *)
 module Scope : sig
-  (** In this floating comment I can refer to type {!t} and value {!v}
-    declared later in the signature *)
+  (** In this floating comment I can refer to type {!t} and value {!v} declared
+      later in the signature *)
 
   type t
 
@@ -155,12 +153,12 @@ module Scope : sig
   val y : int
 
   module A : sig
-    (** In this module I can refer to val {!x} declared above as well as
-      type {!u} declared later in the parent module. Elements declared
-      in this signature take priority, so {!y} refers to {!A.y} as
-      opposed to the [y] declared in the parent signature.
-      
-      @see 'markup.mli' for a good time *)
+    (** In this module I can refer to val {!x} declared above as well as type
+        {!u} declared later in the parent module. Elements declared in this
+        signature take priority, so {!y} refers to {!A.y} as opposed to the [y]
+        declared in the parent signature.
+
+        @see 'markup.mli' for a good time *)
 
     val y : string
   end
@@ -174,25 +172,27 @@ module Preamble_examples : sig
   (** This is the comment attached to the declaration of Hidden__Module *)
   module Hidden__Module : sig
     (** This is the top comment declared in the module Hidden__module.
-     
-     This is the second paragraph in the module Hidden__module.
-     
-     @canonical Odoc_examples.Markup.Module *)
+
+        This is the second paragraph in the module Hidden__module.
+
+        @canonical Odoc_examples.Markup.Module *)
 
     type t
     (** This is a comment on type t *)
   end
 
   module Module = Hidden__Module
-  (** This comment is on the declaration of Module as an alias of Hidden__Module *)
+  (** This comment is on the declaration of Module as an alias of Hidden__Module
+  *)
 
-  (** This is the comment attached to the declaration of module Hidden__Module2 *)
+  (** This is the comment attached to the declaration of module Hidden__Module2
+  *)
   module Hidden__Module2 : sig
     (** This is the top comment declared in the module Hidden__module2.
-       
-       This is the second paragraph in the module Hidden__module2.
-       
-       @canonical Odoc_examples.Markup.Module2 *)
+
+        This is the second paragraph in the module Hidden__module2.
+
+        @canonical Odoc_examples.Markup.Module2 *)
 
     type t
     (** This is a comment on type t *)
@@ -202,23 +202,22 @@ module Preamble_examples : sig
 
   module Nonhidden_module : sig
     (** This is the top comment declared in the module Hidden__module2.
-       
-       This is the second paragraph in the module Hidden__module2.
-    *)
+
+        This is the second paragraph in the module Hidden__module2. *)
   end
 
   module Module3 = Nonhidden_module
-  (** This comment is on the declaration of Module3 as an alias of Nonhidden_module *)
+  (** This comment is on the declaration of Module3 as an alias of
+      Nonhidden_module *)
 
   module Nonhidden_module2 : sig
     (** This is the top comment declared in the module Hidden__module2.
-       
-       This is the second paragraph in the module Hidden__module2.
-    *)
+
+        This is the second paragraph in the module Hidden__module2. *)
   end
 
   module Module4 = Nonhidden_module2
 
   (** The [modules] special reference can be used to refer to a list of modules.
-It uses the synopsis from the modules  *)
+      It uses the synopsis from the modules *)
 end

doc/examples/odoc_examples.ml

@@ -1,7 +1,7 @@
 (** Examples of the output from [odoc] *)
 
-(** These examples are intended to be viewed alongside the
-    source code. See {:https://github.com/ocaml/odoc/tree/master/doc/examples} *)
+(** These examples are intended to be viewed alongside the source code. See
+    {:https://github.com/ocaml/odoc/tree/master/doc/examples} *)
 
 module Expansion = Expansion
 module Resolution = Resolution

doc/examples/resolution.mli

@@ -1,8 +1,8 @@
 (** Examples of Path, Fragment and Reference Resolution *)
 
-(** This module contains examples of some of the features of Resolution
-as described in the page {!page-features}. See the explanations there for
-details on what each of these demonstrates. *)
+(** This module contains examples of some of the features of Resolution as
+    described in the page {!page-features}. See the explanations there for
+    details on what each of these demonstrates. *)
 
 [@@@warning "-67"]
 
@@ -28,7 +28,7 @@ end
 
 module HiddenAlias : sig
   (** Demonstrates a reference to an item in a module that's an alias of a
-  hidden module. *)
+      hidden module. *)
 
   (**/**)
 
@@ -110,8 +110,9 @@ module References : sig
     end
   end
 
-  (** We can refer unambiguously to {!module-type-A.t} in module type [A] or {!module-A.t} in module [A],
-and also where there are name clashes within the path: {!module-A.module-B.t} or {!module-A.module-type-B.t} *)
+  (** We can refer unambiguously to {!module-type-A.t} in module type [A] or
+      {!module-A.t} in module [A], and also where there are name clashes within
+      the path: {!module-A.module-B.t} or {!module-A.module-type-B.t} *)
 end
 
 module Complicated_1 : sig

src/document/doctree.ml

@@ -196,8 +196,8 @@ end
 module Headings : sig
   val fold :
     enter_subpages:bool -> ('a -> Heading.t -> 'a) -> 'a -> Page.t -> 'a
-  (** Fold over every headings, follow nested documentedsrc and
-      expansions, as well as subpages if [enter_subpages] is [true]. *)
+  (** Fold over every headings, follow nested documentedsrc and expansions, as
+      well as subpages if [enter_subpages] is [true]. *)
 
   val foldmap :
     enter_subpages:bool ->

src/document/generator_signatures.ml

@@ -5,8 +5,7 @@ type rendered_item = DocumentedSrc.t
 
 type text = Codefmt.t
 
-(** HTML generation syntax customization module. See {!ML} and
-    {!Reason}. *)
+(** HTML generation syntax customization module. See {!ML} and {!Reason}. *)
 module type SYNTAX = sig
   module Obj : sig
     val close_tag_closed : string

src/document/targets.mli

@@ -1,9 +1,7 @@
-(** Collect all the urls of pages defined by a model. 
-    
-    Roughly a simplified version of the normal process
-    to convert a model into a document, only for extracting Urls.
-    Used to determine the build targets.
-*)
+(** Collect all the urls of pages defined by a model.
+
+    Roughly a simplified version of the normal process to convert a model into a
+    document, only for extracting Urls. Used to determine the build targets. *)
 
 open Odoc_model.Lang
 

src/document/url.mli

@@ -17,8 +17,8 @@ module Path : sig
   val string_of_kind : kind -> string
 
   val pp_disambiguating_prefix : Format.formatter -> kind -> unit
-  (** Print the ["kind-"] prefix used to disambiguate urls in "flat modes":
-      e.g. latex labels and output files in [--flat] HTML and man output *)
+  (** Print the ["kind-"] prefix used to disambiguate urls in "flat modes": e.g.
+      latex labels and output files in [--flat] HTML and man output *)
 
   type t = { kind : kind; parent : t option; name : string }
 
@@ -41,15 +41,14 @@ module Path : sig
     is_dir:(kind -> [ `Always | `Never | `IfNotLast ]) ->
     (kind * string) list ->
     (kind * string) list * (kind * string) list
-  (** [split is_dir path] splits the list [path] into a directory
-      and filename, based on the [is_dir] function. The function
-      [is_dir] should return whether or not the path element [kind]
-      should be a directory or not. If the function [is_dir] returns
-      [`IfNotLast] then the element will be a directory only if it
-      is not the last element in the path. The return value is a tuple
-      of directory-type elements and filename-type elements. If the
-      [is_dir] function can return [`Always], the caller must be prepared
-      to handle the case where the filename part is empty. *)
+  (** [split is_dir path] splits the list [path] into a directory and filename,
+      based on the [is_dir] function. The function [is_dir] should return
+      whether or not the path element [kind] should be a directory or not. If
+      the function [is_dir] returns [`IfNotLast] then the element will be a
+      directory only if it is not the last element in the path. The return value
+      is a tuple of directory-type elements and filename-type elements. If the
+      [is_dir] function can return [`Always], the caller must be prepared to
+      handle the case where the filename part is empty. *)
 end
 
 module Anchor : sig
@@ -75,8 +74,8 @@ module Anchor : sig
     anchor : string;
         (** Anchor in {!field-page} where the element is attached *)
     kind : kind;
-        (** What kind of element the path points to.
-        e.g. "module", "module-type", "exception", ... *)
+        (** What kind of element the path points to. e.g. "module",
+            "module-type", "exception", ... *)
   }
 
   val from_identifier : Identifier.t -> t
@@ -102,18 +101,18 @@ val from_path : Path.t -> t
 val from_identifier : stop_before:bool -> Identifier.t -> t
 (** [from_identifier] turns an identifier to an url.
 
-     Some identifiers can be accessed in different ways. For instance,
-     submodules generate a dedicated page, but they can also be linked to at
-     their parent page, using a hash to the declaration.
+    Some identifiers can be accessed in different ways. For instance, submodules
+    generate a dedicated page, but they can also be linked to at their parent
+    page, using a hash to the declaration.
 
-     The [stop_before] boolean controls that: with [~stop_before:true], the url
-     will point to the parent page when applicable.
+    The [stop_before] boolean controls that: with [~stop_before:true], the url
+    will point to the parent page when applicable.
 
-     There is a pitfall with [from_identifier]: Using [~stop_before:false] with
-     a module that does not contain an expansion, such as a module alias. This
-     will return a [url] leading to a 404 page.
+    There is a pitfall with [from_identifier]: Using [~stop_before:false] with a
+    module that does not contain an expansion, such as a module alias. This will
+    return a [url] leading to a 404 page.
 
-     It would be nice to enforce no 404 by the type system. *)
+    It would be nice to enforce no 404 by the type system. *)
 
 val from_asset_identifier : Identifier.AssetFile.t -> t