diff --git a/src/core/CCArray.mli b/src/core/CCArray.mli
index 651394fd..14c9edf9 100644
--- a/src/core/CCArray.mli
+++ b/src/core/CCArray.mli
@@ -164,7 +164,7 @@ val bsearch : cmp:('a -> 'a -> int) -> 'a -> 'a t ->
   [ `All_lower | `All_bigger | `Just_after of int | `Empty | `At of int ]
 (** [bsearch ?cmp x arr] finds the index of the object [x] in the array [arr],
     provided [arr] is {b sorted} using [cmp]. If the array is not sorted,
-    the result is not specified (may @raise Invalid_argument).
+    the result is not specified
 
     Complexity: [O(log n)] where n is the length of the array
     (dichotomic search).
diff --git a/src/core/CCFloat.mli b/src/core/CCFloat.mli
index 21ef0588..a4778766 100644
--- a/src/core/CCFloat.mli
+++ b/src/core/CCFloat.mli
@@ -132,19 +132,24 @@ module Infix : sig
   (** @since 0.17 *)
 
   val (+) : t -> t -> t
-  (** Addition. @since 2.1 *)
+  (** Addition.
+      @since 2.1 *)
 
   val (-) : t -> t -> t
-  (** Subtraction. @since 2.1 *)
+  (** Subtraction.
+      @since 2.1 *)
 
   val (~-) : t -> t
-  (** Unary negation. @since 2.1 *)
+  (** Unary negation.
+      @since 2.1 *)
 
   val ( * ) : t -> t -> t
-  (** Multiplication. @since 2.1 *)
+  (** Multiplication.
+      @since 2.1 *)
 
   val (/) : t -> t -> t
-  (** Division. @since 2.1 *)
+  (** Division.
+      @since 2.1 *)
 end
 
 include module type of Infix
diff --git a/src/core/CCParse.mli b/src/core/CCParse.mli
index b18d35d0..25b997de 100644
--- a/src/core/CCParse.mli
+++ b/src/core/CCParse.mli
@@ -23,7 +23,7 @@
 
     ]}
 
-    {6 Parse a list of words}
+    {4 Parse a list of words}
 
     {[
       open Containers.Parse;;
@@ -31,7 +31,7 @@
       parse_string_exn p "[abc , de, hello ,world  ]";;
     ]}
 
-    {6 Stress Test}
+    {4 Stress Test}
     This makes a list of 100_000 integers, prints it and parses it back.
 
     {[
diff --git a/src/core/CCRandom.mli b/src/core/CCRandom.mli
index b9c55a5c..b2cf3442 100644
--- a/src/core/CCRandom.mli
+++ b/src/core/CCRandom.mli
@@ -143,13 +143,13 @@ val fix :
     @param sub2 cases that use the recursive gen twice.
     @param subn cases that use a list of recursive cases. *)
 
-(** {6 Applicative} *)
+(** {4 Applicative} *)
 
 val pure : 'a -> 'a t
 
 val (<*>) : ('a -> 'b) t -> 'a t -> 'b t
 
-(** {6 Run a generator} *)
+(** {4 Run a generator} *)
 
 val run : ?st:state -> 'a t -> 'a
 (** Using a random state (possibly the one in argument) run a generator. *)
diff --git a/src/core/CCResult.mli b/src/core/CCResult.mli
index 4f402d4a..e12ea948 100644
--- a/src/core/CCResult.mli
+++ b/src/core/CCResult.mli
@@ -54,7 +54,8 @@ val add_ctx : string -> ('a, string) t -> ('a, string) t
 val add_ctxf : ('a, Format.formatter, unit, ('b, string) t -> ('b, string) t) format4 -> 'a
 (** [add_ctxf format_message] is similar to {!add_ctx} but with
     {!Format} for printing the message (eagerly).
-    Example: {[
+    Example:
+    {[
       add_ctxf "message(number %d, foo: %B)" 42 true (Error "error)"
     ]}
     @since 1.2 *)
diff --git a/src/core/CCString.mli b/src/core/CCString.mli
index 1a551de0..bbf5d8b1 100644
--- a/src/core/CCString.mli
+++ b/src/core/CCString.mli
@@ -295,16 +295,20 @@ val exists2 : (char -> char -> bool) -> string -> string -> bool
     a stable alias for them even in older versions. *)
 
 val capitalize_ascii : string -> string
-(** See {!String}. @since 0.18 *)
+(** See {!String}.
+    @since 0.18 *)
 
 val uncapitalize_ascii : string -> string
-(** See {!String}. @since 0.18 *)
+(** See {!String}.
+    @since 0.18 *)
 
 val uppercase_ascii : string -> string
-(** See {!String}. @since 0.18 *)
+(** See {!String}.
+    @since 0.18 *)
 
 val lowercase_ascii : string -> string
-(** See {!String}. @since 0.18 *)
+(** See {!String}.
+    @since 0.18 *)
 
 val equal_caseless : string -> string -> bool
 (** Comparison without respect to {b ascii} lowercase.
@@ -370,7 +374,7 @@ module Split : sig
 
   val klist : ?drop:drop_if_empty -> by:string -> string -> (string*int*int) klist
 
-  (** {6 Copying functions}
+  (** {4 Copying functions}
 
       Those split functions actually copy the substrings, which can be
       more convenient but less efficient in general. *)
@@ -430,7 +434,9 @@ val edit_distance : string -> string -> int
     distance axioms: it is always positive, symmetric, and satisfies
     the formula [distance a b + distance b c >= distance a c]. *)
 
-(** {2 Slices} A contiguous part of a string *)
+(** {2 Slices}
+    
+    A contiguous part of a string *)
 
 module Sub : sig
   type t = string * int * int
diff --git a/src/data/CCDeque.mli b/src/data/CCDeque.mli
index a214dd9a..db970853 100644
--- a/src/data/CCDeque.mli
+++ b/src/data/CCDeque.mli
@@ -43,16 +43,20 @@ val push_back : 'a t -> 'a -> unit
 (** Push value at the back. *)
 
 val peek_front : 'a t -> 'a
-(** First value, or @raise Empty if empty. *)
+(** First value
+    @raise Empty if empty. *)
 
 val peek_back : 'a t -> 'a
-(** Last value, or @raise Empty if empty. *)
+(** Last value
+    @raise Empty if empty. *)
 
 val take_back : 'a t -> 'a
-(** Take last value, or @raise Empty if empty. *)
+(** Take last value
+    @raise Empty if empty. *)
 
 val take_front : 'a t -> 'a
-(** Take first value, or @raise Empty if empty. *)
+(** Take first value
+    @raise Empty if empty. *)
 
 val append_front : into:'a t -> 'a t -> unit
 (** [append_front ~into q] adds all elements of [q] at the front
diff --git a/src/data/CCHet.mli b/src/data/CCHet.mli
index f6a88f7b..12ba06e0 100644
--- a/src/data/CCHet.mli
+++ b/src/data/CCHet.mli
@@ -23,7 +23,7 @@ end
 type pair =
   | Pair : 'a Key.t * 'a -> pair
 
-(** {2 Imperative table indexed by {!Key}} *)
+(** {2 Imperative table indexed by [Key]} *)
 module Tbl : sig
   type t
 
diff --git a/src/data/CCTrie.mli b/src/data/CCTrie.mli
index 5592bd02..c118d77f 100644
--- a/src/data/CCTrie.mli
+++ b/src/data/CCTrie.mli
@@ -8,7 +8,7 @@ type 'a ktree = unit -> [`Nil | `Node of 'a * 'a ktree list]
 
 (** {2 Signatures} *)
 
-(** {6 A Composite Word}
+(** {4 A Composite Word}
 
     Words are made of characters, who belong to a total order *)
 
@@ -86,7 +86,7 @@ module type S = sig
   val size : _ t -> int
   (** Number of bindings. *)
 
-  (** {6 Conversions} *)
+  (** {4 Conversions} *)
 
   val to_list : 'a t -> (key * 'a) list
 
@@ -100,7 +100,7 @@ module type S = sig
 
   val to_tree : 'a t -> [`Char of char_ | `Val of 'a | `Switch] ktree
 
-  (** {6 Ranges} *)
+  (** {4 Ranges} *)
 
   val above : key -> 'a t -> (key * 'a) sequence
   (** All bindings whose key is bigger or equal to the given key, in
diff --git a/src/iter/CCLazy_list.mli b/src/iter/CCLazy_list.mli
index 95eb3c3e..52ebe477 100644
--- a/src/iter/CCLazy_list.mli
+++ b/src/iter/CCLazy_list.mli
@@ -52,7 +52,9 @@ val default : default:'a t -> 'a t -> 'a t
 module Infix : sig
   val (>|=) : 'a t -> ('a -> 'b) -> 'b t
   val (>>=) : 'a t -> ('a -> 'b t) -> 'b t
-  val (<|>) : 'a t -> 'a t -> 'a t (** Alias to {!default}. @since 2.1 *)
+  val (<|>) : 'a t -> 'a t -> 'a t
+  (** Alias to {!default}.
+      @since 2.1 *)
 end
 
 include module type of Infix
diff --git a/src/threads/CCPool.mli b/src/threads/CCPool.mli
index 69a174d6..c57914e4 100644
--- a/src/threads/CCPool.mli
+++ b/src/threads/CCPool.mli
@@ -39,7 +39,7 @@ module Make(P : PARAM) : sig
   (** After calling [stop ()], most functions will raise Stopped.
       This has the effect of preventing new tasks from being executed. *)
 
-  (** {6 Futures}
+  (** {4 Futures}
 
       The futures are registration points for callbacks, storing a {!state},
       that are executed in the pool using {!run}. *)