diff --git a/jscomp/others/belt_Map.mli b/jscomp/others/belt_Map.mli
index ce9b7040d1..344c09ba4c 100644
--- a/jscomp/others/belt_Map.mli
+++ b/jscomp/others/belt_Map.mli
@@ -12,55 +12,26 @@
 (*  Adapted by authors of ReScript without using functors          *)
 (***********************************************************************)
 
-(** A _immutable_ sorted map module which allows customize _compare_ behavior.
+(** The top level provides generic immutable map operations.
 
-    The implementation uses balanced binary trees, and therefore searching
-    and insertion take time logarithmic in the size of the map.
+    It also has three specialized inner modules `Belt.Map.Int`,
+    `Belt.Map.String` and `Belt.Map.Dict`. *)
 
-    For more info on this module's usage of identity, `make` and others, please see
-    the top level documentation of Belt, **A special encoding for collection safety**.
-
-    Example usage:
-
-    ```
-    module PairComparator = Belt.Id.MakeComparable(struct
-        type t = int * int
-        let cmp (a0, a1) (b0, b1) =
-          match Pervasives.compare a0 b0 with
-          | 0 -> Pervasives.compare a1 b1
-          | c -> c
-      end)
-
-    let myMap = Belt.Map.make ~id:(module PairComparator)
-    let myMap2 = Belt.Map.set myMap (1, 2) "myValue"
+(*  ```res prelude
+    type t<'key, 'value, 'identity>
+    type id<'key, 'id> = Belt_Id.comparable<'key, 'id>
     ```
-
-    The API documentation below will assume a predeclared comparator module for integers, IntCmp
 *)
 
-
-(** Specalized when key type is `int`, more efficient
-    than the generic type, its compare behavior is fixed using the built-in comparison
-*)
 module Int = Belt_MapInt
 
-(** specalized when key type is `string`, more efficient
-    than the generic type, its compare behavior is fixed using the built-in comparison *)
 module String = Belt_MapString
 
-(** This module seprate identity from data, it is a bit more verboe but slightly
-    more efficient due to the fact that there is no need to pack identity and data back
-    after each operation
-
-    **Advanced usage only**
-*)
 module Dict = Belt_MapDict
 
 
 type ('key, 'value, 'identity) t
-(** `('key, 'identity) t`
-
-    `'key` is the field type
+(** `'key` is the field type
 
     `'value` is the element type
 
@@ -69,51 +40,47 @@ type ('key, 'value, 'identity) t
 
 
 type ('key, 'id) id = ('key, 'id) Belt_Id.comparable
-(** The identity needed for making an empty map*)
+(** The identity needed for making an empty map. *)
 
+val make: id:('k, 'id) id -> ('k, 'v, 'id) t
+(** `make(~id)` creates a new map by taking in the comparator.
 
-(*
-    How we retain soundness:
-    The only way to create a value of type `_ t` from scratch
-    is through `empty` which requires `_ Belt_Id.t`
-    The only way to create `_ Belt_Id.t` is using `Belt_Id.Make` which
-    will create a fresh type `id` per module
-
-    Generic operations over tree without `cmp` are still exported
-    (for efficient reasons) so that `data` does not need be boxed and unboxed.
-
-    The soundness is guaranteed in two aspects:
-    When create a value of `_ t` it needs both `_ Belt_Id.t` and `_ t0`.
-    `_ Belt_Id.t` is an abstract type. Note `add0` requires `_ Belt_Id.cmp` which
-    is also an abstract type which can only come from `_ Belt_Id.t`
-
-    When destructing a value of `_ t`, the `'id` parameter is threaded.
-
-*)
-
-(* should not export `Belt_Id.compare`.
-   should only export `Belt_Id.t` or `Belt_Id.cmp` instead *)
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
 
+    let m = Belt.Map.make(~id=module(IntCmp))
 
-val make: id:('k, 'id) id -> ('k, 'v, 'id) t
-(** `make ~id` creates a new map by taking in the comparator
-    ```
-    let m = Belt.Map.make ~id:(module IntCmp)
+    Belt.Map.set(m, 0, "a")
     ```
 *)
 
 
 val isEmpty: _ t -> bool
-(** `isEmpty m` checks whether a map m is empty
-    ```
-    isEmpty (fromArray [|1,"1"|] ~id:(module IntCmp)) = false
+(** `isEmpty(m)` checks whether a map m is empty.
+
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
+
+    Belt.Map.isEmpty(Belt.Map.fromArray([(1, "1")], ~id=module(IntCmp))) == false
     ```
 *)
 
 val has: ('k, 'v, 'id) t -> 'k  -> bool
-(** `has m k` checks whether m has the key k
-    ```
-    has (fromArray [|1,"1"|] ~id:(module IntCmp)) 1 = true
+(** `has(m, k)` checks whether `m` has the key `k`.
+
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
+
+    Belt.Map.has(Belt.Map.fromArray([(1, "1")], ~id=module(IntCmp)), 1) == true
     ```
 *)
 
@@ -127,7 +94,7 @@ val cmp:
   ('k, 'v, 'id) t ->
   ('v -> 'v -> int ) ->
   int
-(** `cmp m0 m1 vcmp`
+(** `cmp(m0, m1, vcmp);`
 
     Total ordering of map given total ordering of value function.
 
@@ -144,233 +111,294 @@ val eq:
   ('k, 'v, 'id) t ->
   ('v -> 'v -> bool) ->
   bool
-(** `eq m1 m2 veq` tests whether the maps `m1` and `m2` are
-    equal, that is, contain equal keys and associate them with
-    equal data.  `veq` is the equality predicate used to compare
-    the data associated with the keys. *)
+(** `eq(m1, m2, veq)` tests whether the maps `m1` and `m2` are equal, that is,
+    contain equal keys and associate them with equal data. `veq` is the
+    equality predicate used to compare the data associated with the keys. *)
 
 val findFirstByU : ('k, 'v, 'id) t -> ('k -> 'v -> bool [@bs]) -> ('k * 'v) option
 val findFirstBy : ('k, 'v, 'id) t -> ('k -> 'v -> bool ) -> ('k * 'v) option
-(** `findFirstBy m p` uses funcion `f` to find the first key value pair
-    to match predicate `p`.
+(** `findFirstBy(m, p)` uses function `f` to find the first key value pair to
+    match predicate `p`.
 
-    ```
-    let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];;
-    findFirstBy s0 (fun k v -> k = 4 ) = option (4, "4");;
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
+
+    let s0 = Belt.Map.fromArray(~id=module(IntCmp), [(4, "4"), (1, "1"), (2, "2"), (3, "")])
+
+    Belt.Map.findFirstBy(s0, (k, v) => k == 4) /* (4, "4") */
     ```
 *)
 
 val forEachU:  ('k, 'v, 'id) t -> ('k -> 'v -> unit [@bs]) -> unit
 val forEach:  ('k, 'v, 'id) t -> ('k -> 'v -> unit) -> unit
-(** `forEach m f` applies `f` to all bindings in map `m`.
-    `f` receives the 'k as first argument, and the associated value
-    as second argument.  The bindings are passed to `f` in increasing
-    order with respect to the ordering over the type of the keys.
+(** `forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the
+    `'k` as first argument, and the associated value as second argument. The
+    bindings are passed to `f` in increasing order with respect to the ordering
+    over the type of the keys.
 
-    ```
-    let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];;
-    let acc = ref [] ;;
-    forEach s0 (fun k v -> acc := (k,v) :: !acc);;
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
+
+    let s0 = Belt.Map.fromArray(~id=module(IntCmp), [(4, "4"), (1, "1"), (2, "2"), (3, "")])
 
-    !acc = [4,"4"; 3,"3"; 2,"2"; 1,"1"]
+    let acc = ref(list{})
+
+    Belt.Map.forEach(s0, (k, v) => acc := list{(k, v), ...acc.contents})
+
+    acc.contents == list{(4, "4"), (3, "3"), (2, "2"), (1, "1")}
     ```
 *)
 
 val reduceU: ('k, 'v, 'id) t -> 'acc -> ('acc -> 'k -> 'v -> 'acc [@bs]) -> 'acc
 val reduce: ('k, 'v, 'id) t -> 'acc -> ('acc -> 'k -> 'v -> 'acc) -> 'acc
-(** `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`,
-    where `k1 ... kN` are the keys of all bindings in `m`
-    (in increasing order), and `d1 ... dN` are the associated data.
-
-    ```
-    let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];;
-    reduce s0 [] (fun acc k v -> (k,v) acc ) = [4,"4";3,"3";2,"2";1,"1"];;
+(** `reduce(m, a, f)` computes `(f(kN, dN) ... (f(k1, d1, a))...)`, where `k1
+    ... kN` are the keys of all bindings in m (in increasing order), and `d1
+    ... dN` are the associated data.
+
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
+
+    let s0 = Belt.Map.fromArray(~id=module(IntCmp), [(4, "4"), (1, "1"), (2, "2"), (3, "3")])
+
+    Belt.Map.reduce(s0, list{}, (acc, k, v) => list{
+      (k, v),
+      ...acc,
+    }) /* [(4, "4"), (3, "3"), (2, "2"), (1, "1"), 0] */
     ```
 *)
 
 val everyU: ('k, 'v, 'id) t -> ('k -> 'v -> bool [@bs]) ->  bool
 val every: ('k, 'v, 'id) t -> ('k -> 'v -> bool) ->  bool
-(** `every m p` checks if all the bindings of the map
-    satisfy the predicate `p`. Order unspecified *)
+(** `every(m, p)` checks if all the bindings of the map satisfy the predicate
+    `p`. Order unspecified *)
 
 val someU: ('k, 'v, 'id) t -> ('k -> 'v -> bool [@bs]) ->  bool
 val some: ('k, 'v, 'id) t -> ('k -> 'v -> bool) ->  bool
-(** `some m p` checks if at least one binding of the map
-    satisfy the predicate `p`. Order unspecified *)
+(** `some(m, p)` checks if at least one binding of the map satisfy the
+    predicate `p`. Order unspecified *)
 
 val size: ('k, 'v, 'id) t -> int
-(** `size s`
+(** `size(s)`
 
-    ```
-    size (fromArray [2,"2"; 2,"1"; 3,"3"] ~id:(module IntCmp)) = 2 ;;
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
+
+    Belt.Map.size(Belt.Map.fromArray([(2, "2"), (2, "1"), (3, "3")], ~id=module(IntCmp))) == 2
     ```
 *)
 
 val toArray: ('k, 'v, 'id) t -> ('k * 'v) array
-(** `toArray s`
-
+(** `toArray(s)`
+
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
+
+    Belt.Map.toArray(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp))) == [
+        (1, "1"),
+        (2, "2"),
+        (3, "3"),
+      ]
     ```
-    toArray (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp)) = [1,"1";2,"2";3,"3"]
-    ```
-
 *)
 
 val toList: ('k, 'v, 'id) t -> ('k * 'v) list
-(** In increasing order
+(** In increasing order.
 
-    **See** [`toArray`]()
+    See `Belt.Map.toArray`
 *)
 
 
 val fromArray:  ('k * 'v) array -> id:('k,'id) id -> ('k,'v,'id) t
-(** `fromArray kvs ~id`
-    ```
-    toArray (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp)) = [1,"1";2,"2";3,"3"]
+(** `fromArray(kvs, ~id);`
+
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
+
+    Belt.Map.toArray(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp))) == [
+        (1, "1"),
+        (2, "2"),
+        (3, "3"),
+      ]
     ```
 *)
 
 val keysToArray: ('k, 'v, 'id) t -> 'k  array
-(** `keysToArray s`
-    ```
-    keysToArray (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp)) =
-    [|1;2;3|];;
+(** `keysToArray(s);`
+
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
+
+    Belt.Map.keysToArray(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp))) == [
+        1,
+        2,
+        3,
+      ]
     ```
 *)
 
 val valuesToArray: ('k, 'v, 'id) t -> 'v  array
-(** `valuesToArray s`
-    ```
-    valuesToArray (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp)) =
-    [|"1";"2";"3"|];;
-    ```
+(** `valuesToArray(s);`
 
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
+
+    Belt.Map.valuesToArray(
+      Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)),
+    ) == ["1", "2", "3"]
+    ```
 *)
 
 val minKey: ('k, _, _) t -> 'k option
-(** `minKey s`
-    **return** the minimum key, None if not exist
-*)
+(** `minKey(s)` returns the minimum key, None if not exist. *)
 
 val minKeyUndefined: ('k, _, _) t -> 'k Js.undefined
-(** **See** [`minKey`]()*)
+(** See `Belt.Map.minKey` *)
 
 val maxKey: ('k, _, _) t -> 'k option
-(** `maxKey s`
-    **return** the maximum key, None if not exist
-*)
+(** `maxKey(s)` returns the maximum key, None if not exist. *)
 
 val maxKeyUndefined: ('k, _, _) t -> 'k Js.undefined
-(** **See** [`maxKey`]() *)
+(** See `Belt.Map.maxKey` *)
 
 val minimum: ('k, 'v,  _) t -> ('k * 'v) option
-(** `minimum s`
-    **return** the minimum key value pair, None if not exist
-*)
+(** `minimum(s)` returns the minimum key value pair, None if not exist. *)
 
 val minUndefined: ('k, 'v, _) t -> ('k * 'v) Js.undefined
-(** **See** [`minimum`]() *)
+(** See `Belt.Map.minimum` *)
 
 val maximum: ('k, 'v, _) t -> ('k * 'v) option
-(** `maximum s`
-    **return** the maximum key value pair, None if not exist
-*)
+(** `maximum(s)` returns the maximum key value pair, None if not exist. *)
 
 val maxUndefined:('k, 'v, _) t -> ('k * 'v) Js.undefined
-(** **See** [`maximum`]()
-*)
+(** See `Belt.Map.maximum` *)
 
 val get:  ('k, 'v, 'id) t -> 'k -> 'v option
-(** `get s k`
+(** `get(s, k)`
 
-    ```
-    get (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp)) 2 =
-    Some "2";;
-    get (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp)) 2 =
-    None;;
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
+
+    Belt.Map.get(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)), 2) ==
+      Some("2")
+
+    Belt.Map.get(Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp)), 2) == None
     ```
 *)
 
 val getUndefined: ('k, 'v, 'id) t -> 'k ->  'v Js.undefined
-(** **See** [`get`]()
+(** See `Belt.Map.get`
 
-    **return** `undefined` when not found
+    Returns `undefined` when not found
 *)
 
 val getWithDefault:
   ('k, 'v, 'id) t -> 'k ->  'v -> 'v
-(** `getWithDefault s k default`
+(** `getWithDefault(s, k, default)`
 
-    **See** [`get`]()
-
-    **return** `default` when `k` is not found
+    See `Belt.Map.get`
 
+    Returns default when `k` is not found.
 *)
 
 val getExn:  ('k, 'v, 'id) t -> 'k -> 'v
-(** `getExn s k`
+(** `getExn(s, k)`
 
-    **See** [`getExn`]()
+    See `Belt.Map.getExn`
 
-    **raise** when `k` not exist
+    raise when `k` not exist
 *)
 
 (****************************************************************************)
 
 val remove:  ('k, 'v, 'id) t -> 'k -> ('k, 'v, 'id) t
-(** `remove m x` when `x` is not in `m`, `m` is returned reference unchanged.
+(** `remove(m, x)` when `x` is not in `m`, `m` is returned reference unchanged.
 
-    ```
-    let s0 =  (fromArray `2,"2"; 1,"1"; 3,"3"` ~id:(module IntCmp));;
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
 
-    let s1 = remove s0 1;;
-    let s2 = remove s1 1;;
-    s1 == s2 ;;
-    keysToArray s1 = [|2;3|];;
-    ```
+    let s0 = Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp))
+
+    let s1 = Belt.Map.remove(s0, 1)
+
+    let s2 = Belt.Map.remove(s1, 1)
+
+    s1 === s2
 
+    Belt.Map.keysToArray(s1) == [2, 3]
+    ```
 *)
 
 val removeMany: ('k, 'v, 'id) t -> 'k array -> ('k, 'v, 'id) t
-(** `removeMany s xs`
+(** `removeMany(s, xs)`
 
-    Removing each of `xs` to `s`, note unlike [`remove`](),
-    the reference of return value might be changed even if none in `xs`
-    exists `s`
+    Removing each of `xs` to `s`, note unlike `Belt.Map.remove`, the reference
+    of return value might be changed even if none in `xs` exists `s`.
 *)
 
 val set:
   ('k, 'v, 'id) t -> 'k -> 'v ->  ('k, 'v, 'id) t
-(** `set m x y ` returns a map containing the same bindings as
-    `m`, with a new binding of `x` to `y`. If `x` was already bound
-    in `m`, its previous binding disappears.
+(** `set(m, x, y)` returns a map containing the same bindings as `m`, with a
+    new binding of `x` to `y`. If `x` was already bound in `m`, its previous
+    binding disappears.
 
-    ```
-    let s0 =  (fromArray [2,"2"; 1,"1"; 3,"3"] ~id:(module IntCmp));;
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = (a, b) => Pervasives.compare(a, b)
+    })
 
-    let s1 = set s0 2 "3";;
+    let s0 = Belt.Map.fromArray([(2, "2"), (1, "1"), (3, "3")], ~id=module(IntCmp))
 
-    valuesToArray s1 =  ["1";"3";"3"];;
+    let s1 = Belt.Map.set(s0, 2, "3")
+
+    Belt.Map.valuesToArray(s1) == ["1", "3", "3"]
     ```
 *)
 
 val updateU: ('k, 'v, 'id) t -> 'k -> ('v option -> 'v option [@bs]) -> ('k, 'v, 'id) t
 val update: ('k, 'v, 'id) t -> 'k -> ('v option -> 'v option) -> ('k, 'v, 'id) t
-(** `update m x f` returns a map containing the same bindings as
-    `m`, except for the binding of `x`.
-    Depending on the value of
-    `y` where `y` is `f (get x m)`, the binding of `x` is
-    added, removed or updated. If `y` is `None`, the binding is
-    removed if it exists; otherwise, if `y` is `Some z` then `x`
-    is associated to `z` in the resulting map.
-*)
+(** `update(m, x, f)` returns a map containing the same bindings as `m`, except
+    for the binding of `x`. Depending on the value of `y` where `y` is
+    `f(get(m, x))`, the binding of `x` is added, removed or updated. If `y` is
+    `None`, the binding is removed if it exists; otherwise, if `y` is `Some(z)`
+    then `x` is associated to `z` in the resulting map. *)
 
 val mergeMany:
   ('k, 'v, 'id) t -> ('k * 'v) array ->  ('k, 'v, 'id) t
-(** `mergeMany s xs`
+(** `mergeMany(s, xs)`
 
-    Adding each of `xs` to `s`, note unlike [`add`](),
-    the reference of return value might be changed even if all values in `xs`
-    exist `s`
+    Adding each of `xs` to `s`, note unlike `add`, the reference of return
+    value might be changed even if all values in `xs` exist `s`.
 *)
 
 val mergeU:
@@ -383,10 +411,9 @@ val merge:
   ('k, 'v2, 'id) t ->
   ('k -> 'v option -> 'v2 option -> 'v3 option) ->
   ('k, 'v3, 'id) t
-(** `merge m1 m2 f` computes a map whose keys is a subset of keys of `m1`
+(** `merge(m1, m2, f)` computes a map whose keys is a subset of keys of `m1`
     and of `m2`. The presence of each such binding, and the corresponding
-    value, is determined with the function `f`.
-*)
+    value, is determined with the function `f`. *)
 
 
 val keepU:
@@ -397,8 +424,8 @@ val keep:
   ('k, 'v, 'id) t ->
   ('k -> 'v -> bool) ->
   ('k, 'v, 'id) t
-(** `keep m p` returns the map with all the bindings in `m`
-    that satisfy predicate `p`. *)
+(** `keep(m, p)` returns the map with all the bindings in m that satisfy
+    predicate `p`. *)
 
 val partitionU:
   ('k, 'v, 'id) t ->
@@ -408,65 +435,57 @@ val partition:
   ('k, 'v, 'id) t ->
   ('k -> 'v -> bool) ->
   ('k, 'v, 'id) t * ('k, 'v, 'id) t
-(** `partition m p` returns a pair of maps `(m1, m2)`, where
-    `m1` contains all the bindings of `s` that satisfy the
-    predicate `p`, and `m2` is the map with all the bindings of
-    `s` that do not satisfy `p`.
-*)
+(** `partition(m, p)` returns a pair of maps `(m1, m2)`, where `m1` contains
+    all the bindings of `s` that satisfy the predicate `p`, and `m2` is the map
+    with all the bindings of `s` that do not satisfy `p`. *)
 
 val split:
   ('k, 'v, 'id) t -> 'k ->
   (('k, 'v, 'id) t * ('k, 'v, 'id) t )* 'v option
-(** `split x m` returns a tuple `(l r), data`, where
-      `l` is the map with all the bindings of `m` whose 'k
-    is strictly less than `x`;
-      `r` is the map with all the bindings of `m` whose 'k
-    is strictly greater than `x`;
-      `data` is `None` if `m` contains no binding for `x`,
-      or `Some v` if `m` binds `v` to `x`.
-*)
+(** `split(x, m)` returns a tuple `(l, r)`, data, where `l` is the map with all
+    the bindings of `m` whose 'k is strictly less than `x`; `r` is the map with
+    all the bindings of m whose 'k is strictly greater than `x`; `data` is
+    `None` if `m` contains no binding for `x`, or `Some(v)` if `m` binds `v` to
+    `x`. *)
 
 val mapU: ('k, 'v, 'id) t -> ('v -> 'v2 [@bs]) ->  ('k, 'v2, 'id) t
 val map: ('k, 'v, 'id) t -> ('v -> 'v2) ->  ('k, 'v2, 'id) t
-(** `map m f` returns a map with same domain as `m`, where the
-    associated value `a` of all bindings of `m` has been
-    replaced by the result of the application of `f` to `a`.
-    The bindings are passed to `f` in increasing order
+(** `map(m, f) returns a map with same domain as`m`, where the associated
+    value`a`of all bindings of`m`has been replaced by the result of the
+    application of`f`to`a`. The bindings are passed to`f` in increasing order
     with respect to the ordering over the type of the keys. *)
 
 val mapWithKeyU: ('k, 'v, 'id) t -> ('k -> 'v -> 'v2 [@bs]) -> ('k, 'v2, 'id) t
 val mapWithKey: ('k, 'v, 'id) t -> ('k -> 'v -> 'v2) -> ('k, 'v2, 'id) t
-(** `mapWithKey m f`
+(** `mapWithKey(m, f)`
 
-    The same as [`map`]() except that `f` is supplied with one more argument: the key
+    The same as `Belt.Map.map` except that `f` is supplied with one more
+    argument: the key.
 *)
 
 
 
 val getData: ('k, 'v, 'id) t -> ('k, 'v, 'id) Belt_MapDict.t
-(** `getData s0`
+(** `getData(s0)`
 
-    **Advanced usage only**
+    Advanced usage only
 
-    **return** the raw data (detached from comparator),
-    but its type is still manifested, so that user can pass identity directly
-    without boxing
+    Returns the raw data (detached from comparator), but its type is still
+    manifested, so that user can pass identity directly without boxing.
 *)
 
 val getId: ('k, 'v, 'id) t -> ('k, 'id) id
-(** `getId s0`
-
-    **Advanced usage only**
+(** Advanced usage only
 
-    **return** the identity of `s0`
+    Returns the identity of s0.
 *)
 
 val packIdData: id:('k, 'id) id -> data:('k, 'v, 'id) Belt_MapDict.t -> ('k, 'v, 'id) t
-(** `packIdData ~id ~data`
+(** `packIdData(~id, ~data)`
 
-    **Advanced usage only**
+    Advanced usage only
 
-    **return** the packed collection
+    Returns the packed collection.
 *)
 
 (**/**)
diff --git a/jscomp/others/belt_MapDict.mli b/jscomp/others/belt_MapDict.mli
index f53a08031e..5eb0bd057f 100644
--- a/jscomp/others/belt_MapDict.mli
+++ b/jscomp/others/belt_MapDict.mli
@@ -22,6 +22,19 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *)
 
+(** This module separates identity from data, it is a bit more verbose but
+    slightly more efficient due to the fact that there is no need to pack
+    identity and data back after each operation.
+
+    **_Advanced usage only_**
+*)
+
+(*  ```res prelude
+    type t<'key, 'value, 'id>
+    type cmp<'key, 'id> = Belt_Id.cmp<'key, 'id>
+    ```
+*)
+
 type ('key, 'value, 'id) t
 
 type ('key, 'id) cmp = ('key, 'id) Belt_Id.cmp
@@ -60,44 +73,49 @@ val eq:
   kcmp:('k, 'id) cmp ->
   veq:('a -> 'a -> bool) ->
   bool
-(** `eq m1 m2 cmp` tests whether the maps `m1` and `m2` are
-    equal, that is, contain equal keys and associate them with
-    equal data.  `cmp` is the equality predicate used to compare
-    the data associated with the keys. *)
+(** `eq(m1, m2, cmp)` tests whether the maps `m1` and `m2` are equal, that is,
+    contain equal keys and associate them with equal data. `cmp` is the
+    equality predicate used to compare the data associated with the keys. *)
 
 val findFirstByU : ('k, 'v, 'id) t -> ('k -> 'v -> bool [@bs]) -> ('k * 'v) option
 val findFirstBy : ('k, 'v, 'id) t -> ('k -> 'v -> bool ) -> ('k * 'v) option
-(** `findFirstBy m p` uses funcion `f` to find the first key value pair
-    to match predicate `p`.
+(** `findFirstBy(m, p)` uses function `f` to find the first key value pair to
+    match predicate `p`.
 
-    ```
-    let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];;
-    findFirstBy s0 (fun k v -> k = 4 ) = option (4, "4");;
+    ```res example
+    module IntCmp = Belt.Id.MakeComparable({
+      type t = int
+      let cmp = Pervasives.compare
+    })
+
+    let s0 = Belt.Map.Dict.fromArray([(4, "4"), (1, "1"), (2, "2"), (3, "3")], ~cmp=IntCmp.cmp)
+
+    Belt.Map.Dict.findFirstBy(s0, (k, _) => k == 4) == Some((4, "4"))
     ```
 *)
 
 val forEachU: ('k, 'a, 'id) t -> ('k -> 'a -> unit [@bs]) -> unit
 val forEach: ('k, 'a, 'id) t -> ('k -> 'a -> unit) -> unit
-(** `forEach m f` applies `f` to all bindings in map `m`.
-    `f` receives the key as first argument, and the associated value
-    as second argument. The bindings are passed to `f` in increasing
-    order with respect to the ordering over the type of the keys. *)
+(** `forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the
+    key as first argument, and the associated value as second argument. The
+    bindings are passed to `f` in increasing order with respect to the ordering
+    over the type of the keys. *)
 
 val reduceU: ('k, 'a, 'id) t -> 'b -> ('b -> 'k -> 'a -> 'b [@bs]) -> 'b
 val reduce: ('k, 'a, 'id) t -> 'b -> ('b -> 'k -> 'a -> 'b) -> 'b
-(** `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`,
-    where `k1 ... kN` are the keys of all bindings in `m`
-    (in increasing order), and `d1 ... dN` are the associated data. *)
+(** `reduce(m, a, f)` computes `f(kN, dN ... f(k1, d1, a)...)`, where `k1 ...
+    kN` are the keys of all bindings in `m` (in increasing order), and `d1 ...
+    dN` are the associated data. *)
 
 val everyU: ('k, 'a, 'id) t -> ('k -> 'a -> bool [@bs]) -> bool
 val every: ('k, 'a, 'id) t -> ('k -> 'a -> bool) -> bool
-(** `every m p` checks if all the bindings of the map
-    satisfy the predicate `p`. Order unspecified *)
+(** `every(m, p)` checks if all the bindings of the map satisfy the predicate
+    `p`. Order unspecified *)
 
 val someU: ('k, 'a, 'id) t -> ('k -> 'a -> bool [@bs]) -> bool
 val some: ('k, 'a, 'id) t -> ('k -> 'a -> bool) -> bool
-(** `some m p` checks if at least one binding of the map
-    satisfy the predicate `p`. Order unspecified *)
+(** `some(m, p)` checks if at least one binding of the map satisfy the
+    predicate `p`. Order unspecified *)
 
 val size: ('k, 'a, 'id) t -> int
 
@@ -150,16 +168,13 @@ val getExn:
   'a
 
 val checkInvariantInternal: _ t -> unit
-(**
-   **raise** when invariant is not held
-*)
 
 val remove:
   ('a, 'b, 'id) t -> 'a ->
   cmp:('a, 'id) cmp ->
   ('a, 'b, 'id) t
-(** `remove m x` returns a map containing the same bindings as
-    `m`, except for `x` which is unbound in the returned map. *)
+(** `remove(m, x)` returns a map containing the same bindings as `m`, except
+    for `x` which is unbound in the returned map. *)
 
 val removeMany:
   ('a, 'b, 'id) t ->
@@ -171,9 +186,9 @@ val set:
   ('a, 'b, 'id) t -> 'a -> 'b ->
   cmp:('a, 'id) cmp ->
   ('a, 'b, 'id) t
-(** `set m x y` returns a map containing the same bindings as
-    `m`, plus a binding of `x` to `y`. If `x` was already bound
-    in `m`, its previous binding disappears. *)
+(** `set(m, x, y)` returns a map containing the same bindings as `m`, plus a
+    binding of `x` to `y`. If `x` was already bound in `m`, its previous
+    binding disappears. *)
 
 val updateU:
   ('a, 'b, 'id) t ->
@@ -198,10 +213,9 @@ val merge:
   ('a, 'c, 'id) t ->
   ('a -> 'b option -> 'c option -> 'd option) ->
   cmp:('a, 'id) cmp -> ('a, 'd, 'id) t
-(** `merge m1 m2 f` computes a map whose keys is a subset of keys of `m1`
+(** `merge(m1, m2, f)` computes a map whose keys is a subset of keys of `m1`
     and of `m2`. The presence of each such binding, and the corresponding
-    value, is determined with the function `f`.
-*)
+    value, is determined with the function `f`. *)
 
 val mergeMany:
   ('a, 'b, 'id) t ->
@@ -217,8 +231,8 @@ val keep:
   ('k, 'a, 'id) t ->
   ('k -> 'a -> bool) ->
   ('k, 'a, 'id) t
-(** `keep m p` returns the map with all the bindings in `m`
-    that satisfy predicate `p`. *)
+(** `keep(m, p)` returns the map with all the bindings in `m` that satisfy
+    predicate `p`. *)
 
 val partitionU:
   ('k, 'a, 'id) t ->
@@ -228,33 +242,27 @@ val partition:
   ('k, 'a, 'id) t ->
   ('k -> 'a -> bool) -> 
   ('k, 'a, 'id) t * ('k, 'a, 'id) t
-(** `partition m p` returns a pair of maps `(m1, m2)`, where
-    `m1` contains all the bindings of `s` that satisfy the
-    predicate `p`, and `m2` is the map with all the bindings of
-    `s` that do not satisfy `p`.
-*)
+(** `partition(m, p)` returns a pair of maps `(m1, m2)`, where `m1` contains
+    all the bindings of `s` that satisfy the predicate `p`, and `m2` is the map
+    with all the bindings of `s` that do not satisfy `p`. *)
 
 val split:
   ('a, 'b, 'id) t ->
   'a ->
   cmp:('a, 'id) cmp ->
   (('a,'b,'id) t * ('a, 'b, 'id) t) * 'b option
-(** `split x m` returns a triple `(l, data, r)`, where
-      `l` is the map with all the bindings of `m` whose key
-    is strictly less than `x`;
-      `r` is the map with all the bindings of `m` whose key
-    is strictly greater than `x`;
-      `data` is `None` if `m` contains no binding for `x`,
-      or `Some v` if `m` binds `v` to `x`.
-*)
+(** `split(x, m)` returns a triple `(l, data, r)`, where `l` is the map with
+    all the bindings of `m` whose key is strictly less than `x`; `r` is the map
+    with all the bindings of `m` whose key is strictly greater than `x`; `data`
+    is `None` if `m` contains no binding for `x`, or `Some(v)` if `m` binds `v`
+    to `x`. *)
 
 val mapU: ('k, 'a, 'id) t -> ('a -> 'b [@bs]) -> ('k ,'b,'id) t
 val map: ('k, 'a, 'id) t -> ('a -> 'b) -> ('k ,'b,'id) t
-(** `map m f` returns a map with same domain as `m`, where the
-    associated value `a` of all bindings of `m` has been
-    replaced by the result of the application of `f` to `a`.
-    The bindings are passed to `f` in increasing order
-    with respect to the ordering over the type of the keys. *)
+(** `map(m, f)` returns a map with same domain as `m`, where the associated
+    value `a` of all bindings of `m` has been replaced by the result of the
+    application of `f` to `a`. The bindings are passed to `f` in increasing
+    order with respect to the ordering over the type of the keys. *)
 
 val mapWithKeyU: ('k, 'a, 'id) t -> ('k -> 'a -> 'b [@bs]) -> ('k, 'b, 'id) t
 val mapWithKey: ('k, 'a, 'id) t -> ('k -> 'a -> 'b) -> ('k, 'b, 'id) t
diff --git a/jscomp/others/belt_MapInt.mli b/jscomp/others/belt_MapInt.mli
index e61bc83722..c1cc656f64 100644
--- a/jscomp/others/belt_MapInt.mli
+++ b/jscomp/others/belt_MapInt.mli
@@ -1,3 +1,12 @@
+(** Specalized when key type is `int`, more efficient than the generic type,
+    its compare behavior is fixed using the built-in comparison. *)
+
+(*  ```res prelude
+    type key = int
+    type t<'value>
+    ```
+*)
+
 # 4 "others/map.cppo.mli"
 type key = int
 # 8 "others/map.cppo.mli"
@@ -15,50 +24,43 @@ val cmp: 'v t -> 'v t -> ('v -> 'v -> int) -> int
 
 val eqU: 'v t -> 'v t -> ('v -> 'v -> bool [@bs]) -> bool
 val eq: 'v t -> 'v t -> ('v -> 'v -> bool) -> bool
-(**
-  `eq m1 m2` tests whether the maps `m1` and `m2` are
-  equal, that is, contain equal keys and associate them with
-  equal data.
-*)
+(** `eq(m1,m2)` tests whether the maps `m1` and `m2` are equal, that is,
+    contain equal keys and associate them with equal data. *)
 
 val findFirstByU : 'v t -> (key -> 'v -> bool [@bs]) -> (key * 'v) option
 val findFirstBy : 'v t -> (key -> 'v -> bool) -> (key * 'v) option
-(**
-  `findFirstBy m p` uses funcion `f` to find the first key value pair
-  to match predicate `p`.
-
-  ```
-  let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];;
-  findFirstBy s0 (fun k v -> k = 4 ) = option (4, "4");;
-  ```
+(** `findFirstBy(m, p)` uses function `f` to find the first key value pair to
+    match predicate `p`.
+
+    ```res example
+    let s0 = Belt.Map.Int.fromArray([(4, "4"), (1, "1"), (2, "2"), (3, "3")])
+
+    Belt.Map.Int.findFirstBy(s0, (k, v) => k == 4) == Some((4, "4"))
+    ```
 *)
 
 val forEachU: 'v t -> (key -> 'v -> unit [@bs]) -> unit
 val forEach: 'v t -> (key -> 'v -> unit) -> unit
-(**
-  `forEach m f` applies `f` to all bindings in map `m`.
-  `f` receives the key as first argument, and the associated value
-  as second argument. The bindings are passed to `f` in increasing
-  order with respect to the ordering over the type of the keys.
-*)
+(** `forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the
+    key as first argument, and the associated value as second argument. The
+    bindings are passed to `f` in increasing order with respect to the ordering
+    over the type of the keys. *)
 
 val reduceU: 'v t -> 'v2 -> ('v2 -> key -> 'v -> 'v2 [@bs]) -> 'v2
 val reduce: 'v t -> 'v2 -> ('v2 -> key -> 'v -> 'v2) -> 'v2
-(**
-  `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`,
-  where `k1 ... kN` are the keys of all bindings in `m`
-  (in increasing order), and `d1 ... dN` are the associated data.
-*)
+(** `reduce(m, a, f)` computes `f(kN, dN, ... f(k1, d1, a)...)`, where `k1 ...
+    kN` are the keys of all bindings in `m` (in increasing order), and `d1 ...
+    dN` are the associated data. *)
 
 val everyU: 'v t -> (key -> 'v -> bool [@bs]) -> bool
 val every: 'v t -> (key -> 'v -> bool) -> bool
-(** `every m p` checks if all the bindings of the map
-    satisfy the predicate `p`. Order unspecified *)
+(** `every(m, p)` checks if all the bindings of the map satisfy the predicate
+    `p`. Order unspecified *)
 
 val someU: 'v t -> (key -> 'v -> bool [@bs]) -> bool
 val some: 'v t -> (key -> 'v -> bool) -> bool
-(** `some m p` checks if at least one binding of the map
-    satisfy the predicate `p`. Order unspecified *)
+(** `some(m, p)` checks if at least one binding of the map satisfy the
+    predicate `p`. Order unspecified *)
 
 val size: 'v t -> int
 
@@ -99,22 +101,18 @@ val getWithDefault: 'v t -> key -> 'v -> 'v
 val getExn: 'v t -> key -> 'v
 
 val checkInvariantInternal: _ t -> unit
-(**
-  **raise** when invariant is not held
-*)
+(** **raise** when invariant is not held. *)
 
 val remove: 'v t -> key -> 'v t
-(** `remove m x` returns a map containing the same bindings as
-    `m`, except for `x` which is unbound in the returned map. *)
+(** `remove(m, x)` returns a map containing the same bindings as `m`, except
+    for `x` which is unbound in the returned map. *)
 
 val removeMany: 'v t -> key array -> 'v t
 
 val set: 'v t -> key -> 'v -> 'v t
-(**
-  `set m x y` returns a map containing the same bindings as
-  `m`, plus a binding of `x` to `y`. If `x` was already bound
-  in `m`, its previous binding disappears.
-*)
+(** `set(m, x, y)` returns a map containing the same bindings as `m`, plus a
+    binding of `x` to `y`. If `x` was already bound in `m`, its previous
+    binding disappears. *)
 
 val updateU: 'v t -> key -> ('v option -> 'v option [@bs]) -> 'v t
 val update: 'v t -> key -> ('v option -> 'v option) -> 'v t
@@ -127,11 +125,9 @@ val merge:
   'v t -> 'v2 t ->
   (key -> 'v option -> 'v2 option -> 'c option) ->
   'c t
-(**
-  `merge m1 m2 f` computes a map whose keys is a subset of keys of `m1`
-  and of `m2`. The presence of each such binding, and the corresponding
-  value, is determined with the function `f`.
-*)
+(** `merge(m1, m2, f)` computes a map whose keys is a subset of keys of `m1`
+    and of `m2`. The presence of each such binding, and the corresponding
+    value, is determined with the function `f`. *)
 
 val mergeMany: 'v t -> (key * 'v) array -> 'v t
 
@@ -144,8 +140,6 @@ val keep:
   'v t ->
   (key -> 'v -> bool) ->
   'v t
-(** `keep m p` returns the map with all the bindings in `m`
-    that satisfy predicate `p`. *)
 
 val partitionU:
   'v t ->
@@ -155,33 +149,23 @@ val partition:
   'v t ->
   (key -> 'v -> bool) ->
   'v t * 'v t
-(**
-  `partition m p` returns a pair of maps `(m1, m2)`, where
-  `m1` contains all the bindings of `s` that satisfy the
-  predicate `p`, and `m2` is the map with all the bindings of
-  `s` that do not satisfy `p`.
-*)
+(** `partition(m, p)` returns a pair of maps `(m1, m2)`, where `m1` contains
+    all the bindings of `s` that satisfy the predicate `p`, and `m2` is the map
+    with all the bindings of `s` that do not satisfy `p`. *)
 
 val split: key -> 'v t -> 'v t * 'v option * 'v t
-(**
-  `split x m` returns a triple `(l, data, r)`, where
-  `l` is the map with all the bindings of `m` whose key
-  is strictly less than `x`;
-  `r` is the map with all the bindings of `m` whose key
-  is strictly greater than `x`;
-  `data` is `None` if `m` contains no binding for `x`,
-  or `Some v` if `m` binds `v` to `x`.
-*)
+(** `split(x, m)` returns a triple `(l, data, r)`, where `l` is the map with
+    all the bindings of `m` whose key is strictly less than `x`; `r` is the map
+    with all the bindings of `m` whose key is strictly greater than `x`; `data`
+    is `None` if m contains no binding for `x`, or `Some(v)` if `m` binds `v`
+    to `x`. *)
 
 val mapU: 'v t -> ('v -> 'v2 [@bs]) -> 'v2 t
 val map: 'v t -> ('v -> 'v2) -> 'v2 t
-(**
-  `map m f` returns a map with same domain as `m`, where the
-  associated value `a` of all bindings of `m` has been
-  replaced by the result of the application of `f` to `a`.
-  The bindings are passed to `f` in increasing order
-  with respect to the ordering over the type of the keys.
-*)
+(** `map(m, f)` returns a map with same domain as `m`, where the associated
+    value `a` of all bindings of `m` has been replaced by the result of the
+    application of `f` to `a`. The bindings are passed to `f` in increasing
+    order with respect to the ordering over the type of the keys. *)
 
 val mapWithKeyU: 'v t -> (key -> 'v -> 'v2 [@bs]) -> 'v2 t
 val mapWithKey: 'v t -> (key -> 'v -> 'v2) -> 'v2 t
diff --git a/jscomp/others/belt_MapString.mli b/jscomp/others/belt_MapString.mli
index bb81370663..656b50d7ae 100644
--- a/jscomp/others/belt_MapString.mli
+++ b/jscomp/others/belt_MapString.mli
@@ -1,3 +1,13 @@
+(** Specalized when key type is `string`, more efficient than the generic type,
+    its compare behavior is fixed using the built-in comparison
+*)
+
+(*  ```res prelude
+    type key = string
+    type t<'value>
+    ```
+*)
+
 # 2 "others/map.cppo.mli"
 type key = string
 # 8 "others/map.cppo.mli"
@@ -15,50 +25,43 @@ val cmp: 'v t -> 'v t -> ('v -> 'v -> int) -> int
 
 val eqU: 'v t -> 'v t -> ('v -> 'v -> bool [@bs]) -> bool
 val eq: 'v t -> 'v t -> ('v -> 'v -> bool) -> bool
-(**
-  `eq m1 m2` tests whether the maps `m1` and `m2` are
-  equal, that is, contain equal keys and associate them with
-  equal data.
-*)
+(** `eq(m1, m2)` tests whether the maps `m1` and `m2` are equal, that is,
+    contain equal keys and associate them with equal data. *)
 
 val findFirstByU : 'v t -> (key -> 'v -> bool [@bs]) -> (key * 'v) option
 val findFirstBy : 'v t -> (key -> 'v -> bool) -> (key * 'v) option
-(**
-  `findFirstBy m p` uses funcion `f` to find the first key value pair
-  to match predicate `p`.
-
-  ```
-  let s0 = fromArray ~id:(module IntCmp) [|4,"4";1,"1";2,"2,"3""|];;
-  findFirstBy s0 (fun k v -> k = 4 ) = option (4, "4");;
-  ```
+(** `findFirstBy(m, p)` uses function `f` to find the first key value pair to
+    match predicate `p`.
+
+    ```res example
+    let s0 = Belt.Map.String.fromArray([("4", 4), ("1", 1), ("2", 2), ("3", 3)])
+
+    Belt.Map.String.findFirstBy(s0, (k, _) => k == "4") == Some(("4", 4))
+    ```
 *)
 
 val forEachU: 'v t -> (key -> 'v -> unit [@bs]) -> unit
 val forEach: 'v t -> (key -> 'v -> unit) -> unit
-(**
-  `forEach m f` applies `f` to all bindings in map `m`.
-  `f` receives the key as first argument, and the associated value
-  as second argument. The bindings are passed to `f` in increasing
-  order with respect to the ordering over the type of the keys.
-*)
+(** `forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the
+    key as first argument, and the associated value as second argument. The
+    bindings are passed to `f` in increasing order with respect to the ordering
+    over the type of the keys. *)
 
 val reduceU: 'v t -> 'v2 -> ('v2 -> key -> 'v -> 'v2 [@bs]) -> 'v2
 val reduce: 'v t -> 'v2 -> ('v2 -> key -> 'v -> 'v2) -> 'v2
-(**
-  `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`,
-  where `k1 ... kN` are the keys of all bindings in `m`
-  (in increasing order), and `d1 ... dN` are the associated data.
-*)
+(** `reduce(m, a, f)` computes `f(kN, dN ... f(k1, d1, a)...), where k1 ...
+    kN)` are the keys of all bindings in `m` (in increasing order), and `d1 ...
+    dN` are the associated data. *)
 
 val everyU: 'v t -> (key -> 'v -> bool [@bs]) -> bool
 val every: 'v t -> (key -> 'v -> bool) -> bool
-(** `every m p` checks if all the bindings of the map
-    satisfy the predicate `p`. Order unspecified *)
+(** `every(m, p)` checks if all the bindings of the map satisfy the predicate
+    `p`. Order unspecified *)
 
 val someU: 'v t -> (key -> 'v -> bool [@bs]) -> bool
 val some: 'v t -> (key -> 'v -> bool) -> bool
-(** `some m p` checks if at least one binding of the map
-    satisfy the predicate `p`. Order unspecified *)
+(** `some(m, p)` checks if at least one binding of the map satisfy the
+    predicate `p`. Order unspecified *)
 
 val size: 'v t -> int
 
@@ -99,22 +102,18 @@ val getWithDefault: 'v t -> key -> 'v -> 'v
 val getExn: 'v t -> key -> 'v
 
 val checkInvariantInternal: _ t -> unit
-(**
-  **raise** when invariant is not held
-*)
+(** **raise** when invariant is not held *)
 
 val remove: 'v t -> key -> 'v t
-(** `remove m x` returns a map containing the same bindings as
-    `m`, except for `x` which is unbound in the returned map. *)
+(** `remove(m, x)` returns a map containing the same bindings as `m`, except
+    for `x` which is unbound in the returned map. *)
 
 val removeMany: 'v t -> key array -> 'v t
 
 val set: 'v t -> key -> 'v -> 'v t
-(**
-  `set m x y` returns a map containing the same bindings as
-  `m`, plus a binding of `x` to `y`. If `x` was already bound
-  in `m`, its previous binding disappears.
-*)
+(** `set(m, x, y)` returns a map containing the same bindings as `m`, plus a
+    binding of `x` to `y`. If `x` was already bound in `m`, its previous
+    binding disappears. *)
 
 val updateU: 'v t -> key -> ('v option -> 'v option [@bs]) -> 'v t
 val update: 'v t -> key -> ('v option -> 'v option) -> 'v t
@@ -127,11 +126,9 @@ val merge:
   'v t -> 'v2 t ->
   (key -> 'v option -> 'v2 option -> 'c option) ->
   'c t
-(**
-  `merge m1 m2 f` computes a map whose keys is a subset of keys of `m1`
-  and of `m2`. The presence of each such binding, and the corresponding
-  value, is determined with the function `f`.
-*)
+(** `merge(m1, m2, f)` computes a map whose keys is a subset of keys of `m1`
+    and of `m2`. The presence of each such binding, and the corresponding
+    value, is determined with the function `f`. *)
 
 val mergeMany: 'v t -> (key * 'v) array -> 'v t
 
@@ -144,8 +141,8 @@ val keep:
   'v t ->
   (key -> 'v -> bool) ->
   'v t
-(** `keep m p` returns the map with all the bindings in `m`
-    that satisfy predicate `p`. *)
+(** `keep(m, p)` returns the map with all the bindings in `m` that satisfy
+    predicate `p`. *)
 
 val partitionU:
   'v t ->
@@ -155,33 +152,23 @@ val partition:
   'v t ->
   (key -> 'v -> bool) ->
   'v t * 'v t
-(**
-  `partition m p` returns a pair of maps `(m1, m2)`, where
-  `m1` contains all the bindings of `s` that satisfy the
-  predicate `p`, and `m2` is the map with all the bindings of
-  `s` that do not satisfy `p`.
-*)
+(** `partition(m, p)` returns a pair of maps `(m1, m2)`, where `m1` contains
+    all the bindings of `s` that satisfy the predicate `p`, and `m2` is the map
+    with all the bindings of s that do not satisfy `p`. *)
 
 val split: key -> 'v t -> 'v t * 'v option * 'v t
-(**
-  `split x m` returns a triple `(l, data, r)`, where
-  `l` is the map with all the bindings of `m` whose key
-  is strictly less than `x`;
-  `r` is the map with all the bindings of `m` whose key
-  is strictly greater than `x`;
-  `data` is `None` if `m` contains no binding for `x`,
-  or `Some v` if `m` binds `v` to `x`.
-*)
+(** `split(x, m)` returns a triple `(l, data, r)`, where `l` is the map with
+    all the bindings of `m` whose key is strictly less than `x`; `r` is the map
+    with all the bindings of m whose key is strictly greater than `x`; `data`
+    is `None` if `m` contains no binding for `x`, or `Some(v)` if `m` binds `v`
+    to `x`. *)
 
 val mapU: 'v t -> ('v -> 'v2 [@bs]) -> 'v2 t
 val map: 'v t -> ('v -> 'v2) -> 'v2 t
-(**
-  `map m f` returns a map with same domain as `m`, where the
-  associated value `a` of all bindings of `m` has been
-  replaced by the result of the application of `f` to `a`.
-  The bindings are passed to `f` in increasing order
-  with respect to the ordering over the type of the keys.
-*)
+(** `map(m, f)` returns a map with same domain as `m`, where the associated
+    value `a` of all bindings of `m` has been replaced by the result of the
+    application of `f` to `a`. The bindings are passed to `f` in increasing
+    order with respect to the ordering over the type of the keys. *)
 
 val mapWithKeyU: 'v t -> (key -> 'v -> 'v2 [@bs]) -> 'v2 t
 val mapWithKey: 'v t -> (key -> 'v -> 'v2) -> 'v2 t
diff --git a/jscomp/others/belt_MutableMap.mli b/jscomp/others/belt_MutableMap.mli
index c2d7960398..99f39f208a 100644
--- a/jscomp/others/belt_MutableMap.mli
+++ b/jscomp/others/belt_MutableMap.mli
@@ -27,9 +27,15 @@ module Int = Belt_MutableMapInt
 module String = Belt_MutableMapString
 
 
-(** A **mutable** sorted map module which allows customize _compare_ behavior.
+(** A mutable sorted map module which allows customize compare behavior.
 
-    Same as Belt.Map, but mutable.
+    Same as `Belt.Map`, but mutable.
+*)
+
+(*  ```res prelude
+    type t<'k, 'v, 'id>
+    type id<'key, 'id> = Belt_Id.comparable<'key, 'id>
+    ```
 *)
 
 type ('k,'v,'id) t
@@ -50,52 +56,46 @@ val cmp:
   ('k, 'a, 'id) t ->
   ('a -> 'a -> int ) ->
   int
-(** `cmp m1 m2 cmp`
-    First compare by size, if size is the same,
-    compare by key, value pair
-*)
+(** `cmp(m1, m2, cmp)` First compare by size, if size is the same, compare by
+    key, value pair. *)
 
 val eqU:  ('k, 'a, 'id) t -> ('k, 'a, 'id) t -> ('a -> 'a -> bool [@bs]) -> bool
 val eq:  ('k, 'a, 'id) t -> ('k, 'a, 'id) t -> ('a -> 'a -> bool) -> bool
-(** `eq m1 m2 eqf` tests whether the maps `m1` and `m2` are
-    equal, that is, contain equal keys and associate them with
-    equal data.  `eqf` is the equality predicate used to compare
-    the data associated with the keys. *)
+(** `eq(m1, m2, eqf)` tests whether the maps `m1` and `m2` are equal, that is,
+    contain equal keys and associate them with equal data. `eqf` is the
+    equality predicate used to compare the data associated with the keys. *)
 
 val forEachU:  ('k, 'a, 'id) t -> ('k -> 'a -> unit [@bs]) -> unit
 val forEach:  ('k, 'a, 'id) t -> ('k -> 'a -> unit) -> unit
-(** `forEach m f` applies `f` to all bindings in map `m`.
-    `f` receives the 'k as first argument, and the associated value
-    as second argument.  The bindings are passed to `f` in increasing
-    order with respect to the ordering over the type of the keys. *)
+(** `forEach(m, f)` applies f to all bindings in map `m`. `f` receives the `'k`
+    as first argument, and the associated value as second argument. The
+    bindings are passed to `f` in increasing order with respect to the ordering
+    over the type of the keys. *)
 
 val reduceU: ('k, 'a, 'id) t -> 'b ->  ('b -> 'k -> 'a -> 'b [@bs]) ->  'b
 val reduce: ('k, 'a, 'id) t -> 'b ->  ('b -> 'k -> 'a -> 'b) ->  'b
-(** `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`,
-    where `k1 ... kN` are the keys of all bindings in `m`
-    (in increasing order), and `d1 ... dN` are the associated data. *)
+(** `reduce(m, a, f), computes`(f(kN, dN) ... (f(k1, d1, a))...)`, where`k1 ...
+    kN`are the keys of all bindings in`m`(in increasing order), and`d1 ... dN`
+    are the associated data. *)
 
 val everyU: ('k, 'a, 'id) t -> ('k -> 'a -> bool [@bs]) ->  bool
 val every: ('k, 'a, 'id) t -> ('k -> 'a -> bool) ->  bool
-(** `every m p` checks if all the bindings of the map
-    satisfy the predicate `p`.
-*)
+(** `every(m, p)` checks if all the bindings of the map satisfy the predicate
+    `p`. *)
 
 
 val someU: ('k, 'a, 'id) t -> ('k -> 'a -> bool [@bs]) ->  bool
 val some: ('k, 'a, 'id) t -> ('k -> 'a -> bool) ->  bool
-(** `some m p` checks if at least one binding of the map
-    satisfy the predicate `p`.
-*)
+(** `some(m, p)` checks if at least one binding of the map satisfy the
+    predicate `p`. *)
 
 val size: ('k, 'a, 'id) t -> int
 
 
 val toList: ('k, 'a, 'id) t -> ('k * 'a) list
-(** In increasing order*)
+(** In increasing order. *)
 
 val toArray: ('k, 'a, 'id) t -> ('k * 'a) array
-(** In increasing order*)
 
 val fromArray: ('k * 'a) array -> id:('k,'id) id ->  ('k,'a,'id) t
 val keysToArray: ('k, _, _) t -> 'k array
@@ -114,9 +114,7 @@ val getWithDefault:
   ('k, 'a, 'id) t -> 'k ->  'a -> 'a
 val getExn:  ('k, 'a, 'id) t -> 'k ->  'a
 val checkInvariantInternal: _ t -> unit
-(**
-   **raise** when invariant is not held
-*)
+(** Raise when invariant is not held. *)
 
 
 (****************************************************************************)
@@ -124,13 +122,12 @@ val checkInvariantInternal: _ t -> unit
 (*TODO: add functional `merge, partition, keep, split`*)
 
 val remove:  ('k, 'a, 'id) t -> 'k -> unit
-(** `remove m x` do the in-place modification,
-*)
+(** `remove(m, x)` do the in-place modification. *)
 
 val removeMany: ('k, 'a, 'id) t -> 'k array -> unit
 
 val set: ('k, 'a, 'id) t -> 'k -> 'a ->  unit
-(** `set m x y ` do the in-place modification *)
+(** `set(m, x, y)` do the in-place modification *)
 
 val updateU: ('k, 'a, 'id) t -> 'k -> ('a option -> 'a option [@bs]) -> unit
 val update: ('k, 'a, 'id) t -> 'k -> ('a option -> 'a option) -> unit
@@ -139,14 +136,10 @@ val mergeMany:  ('k, 'a, 'id) t -> ('k * 'a) array ->  unit
 
 val mapU: ('k, 'a, 'id) t -> ('a -> 'b [@bs]) ->  ('k ,'b,'id ) t
 val map: ('k, 'a, 'id) t -> ('a -> 'b) ->  ('k ,'b,'id ) t
-(** `map m f` returns a map with same domain as `m`, where the
-    associated value `a` of all bindings of `m` has been
-    replaced by the result of the application of `f` to `a`.
-    The bindings are passed to `f` in increasing order
-    with respect to the ordering over the type of the keys. *)
+(** `map(m, f)` returns a map with same domain as `m`, where the associated
+    value a of all bindings of `m` has been replaced by the result of the
+    application of `f` to `a`. The bindings are passed to `f` in increasing
+    order with respect to the ordering over the type of the keys. *)
 
 val mapWithKeyU: ('k, 'a, 'id) t -> ('k -> 'a -> 'b [@bs]) -> ('k, 'b, 'id) t
 val mapWithKey: ('k, 'a, 'id) t -> ('k -> 'a -> 'b) -> ('k, 'b, 'id) t
-
-
-
diff --git a/jscomp/others/belt_MutableMapInt.mli b/jscomp/others/belt_MutableMapInt.mli
index 432f036946..dbb4128edf 100644
--- a/jscomp/others/belt_MutableMapInt.mli
+++ b/jscomp/others/belt_MutableMapInt.mli
@@ -23,6 +23,12 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *)
 
+(*  ```res prelude
+    type key = int
+    type t<'a>
+    ```
+*)
+
 # 28 "others/mapm.cppo.mli"
 type key = int
 # 32 "others/mapm.cppo.mli"
@@ -37,41 +43,34 @@ val has:  'a t -> key -> bool
 
 val cmpU:  'a t -> 'a t -> ('a -> 'a -> int [@bs]) -> int
 val cmp:  'a t -> 'a t -> ('a -> 'a -> int) -> int
-(** `cmp m1 m2 cmp`
-  First compare by size, if size is the same,
-  compare by key, value pair
-*)
+(** `cmp(m1, m2, cmp)` First compare by size, if size is the same, compare by
+    key, value pair. *)
 
 val eqU: 'a t -> 'a t -> ('a -> 'a -> bool [@bs]) -> bool
 val eq: 'a t -> 'a t -> ('a -> 'a -> bool ) -> bool
-(** `eq m1 m2 cmp` *)
+(** `eq(m1, m2, cmp)` *)
 
 val forEachU: 'a t -> (key -> 'a -> unit [@bs]) ->  unit
 val forEach: 'a t -> (key -> 'a -> unit) ->  unit
-(** `forEach m f` applies `f` to all bindings in map `m`.
-  `f` receives the key as first argument, and the associated value
-  as second argument.
-  The application order of `f`  is in increasing order. *)
+(** `forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the
+    key as first argument, and the associated value as second argument. The
+    application order of `f` is in increasing order. *)
 
 val reduceU:  'a t -> 'b -> ('b -> key -> 'a -> 'b [@bs]) -> 'b
 val reduce:  'a t -> 'b -> ('b -> key -> 'a -> 'b ) -> 'b
-(** `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`,
-  where `k1 ... kN` are the keys of all bindings in `m`
-  (in increasing order), and `d1 ... dN` are the associated data. *)
+(** `reduce(m, a, f), computes`(f(kN, dN) ... (f(k1, d1, a))...)`, where`k1 ...
+    kN`are the keys of all bindings in`m`(in increasing order), and`d1 ... dN`
+    are the associated data. *)
 
 val everyU:  'a t -> (key -> 'a -> bool [@bs]) -> bool
 val every:  'a t -> (key -> 'a -> bool) -> bool
-(** `every m p` checks if all the bindings of the map
-  satisfy the predicate `p`.
-  The application order of `p` is unspecified.
-*)
+(** `every(m, p)` checks if all the bindings of the map satisfy the predicate
+    `p`. The application order of `p` is unspecified. *)
 
 val someU:  'a t -> (key -> 'a -> bool [@bs]) -> bool
 val some:  'a t -> (key -> 'a -> bool) -> bool
-(** `some m p` checks if at least one binding of the map
-  satisfy the predicate `p`.
-  The application order of `p` is unspecified.
-*)
+(** `some(m, p)` checks if at least one binding of the map satisfy the
+    predicate `p`. The application order of `p` is unspecified. *)
 
 
 
@@ -81,7 +80,6 @@ val toList: 'a t -> (key * 'a) list
 (** In increasing order *)
 
 val toArray: 'a t -> (key * 'a) array
-(** In increasing order *)
 
 val fromArray: (key * 'a) array -> 'a t
 val keysToArray: 'a t -> key array
@@ -99,9 +97,7 @@ val getUndefined: 'a t -> key -> 'a Js.undefined
 val getWithDefault:  'a t -> key -> 'a  -> 'a
 val getExn: 'a t -> key -> 'a
 val checkInvariantInternal: _ t -> unit
-(**
-  **raise** when invariant is not held
-*)
+(** Raise when invariant is not held. *)
 
 
 
@@ -110,14 +106,13 @@ val checkInvariantInternal: _ t -> unit
 (*TODO: add functional `merge, partition, keep, split`*)
 
 val remove: 'a t -> key -> unit
-(** `remove m x` do the in-place modification *)
+(** `remove(m, x)` do the in-place modification. *)
 
 val removeMany: 'a t -> key array -> unit
 
 val set: 'a t -> key -> 'a -> unit
-(** `set m x y` do the in-place modification, return
-  `m` for chaining. If `x` was already bound
-  in `m`, its previous binding disappears. *)
+(** `set(m, x, y)` do the in-place modification, return `m` for chaining. If
+    `x` was already bound in `m`, its previous binding disappears. *)
 
 val updateU: 'a t -> key -> ('a option -> 'a option [@bs]) -> unit
 val update: 'a t -> key -> ('a option -> 'a option) -> unit
@@ -125,11 +120,10 @@ val update: 'a t -> key -> ('a option -> 'a option) -> unit
 
 val mapU: 'a t -> ('a -> 'b [@bs]) ->  'b t
 val map: 'a t -> ('a -> 'b) ->  'b t
-(** `map m f` returns a map with same domain as `m`, where the
-  associated value `a` of all bindings of `m` has been
-  replaced by the result of the application of `f` to `a`.
-  The bindings are passed to `f` in increasing order
-  with respect to the ordering over the type of the keys. *)
+(** `map(m, f)` returns a map with same domain as `m`, where the associated
+    value a of all bindings of `m` has been replaced by the result of the
+    application of `f` to `a`. The bindings are passed to `f` in increasing
+    order with respect to the ordering over the type of the keys. *)
 
 val mapWithKeyU: 'a t -> (key -> 'a -> 'b [@bs]) -> 'b t
 val mapWithKey: 'a t -> (key -> 'a -> 'b) -> 'b t
diff --git a/jscomp/others/belt_MutableMapString.mli b/jscomp/others/belt_MutableMapString.mli
index 3223a496ac..a93530bb77 100644
--- a/jscomp/others/belt_MutableMapString.mli
+++ b/jscomp/others/belt_MutableMapString.mli
@@ -23,8 +23,15 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *)
 
+(*  ```res prelude
+    type key = string
+    type t<'a>
+    ```
+*)
+
 # 26 "others/mapm.cppo.mli"
 type key = string
+
 # 32 "others/mapm.cppo.mli"
 type 'a t
 
@@ -37,41 +44,34 @@ val has:  'a t -> key -> bool
 
 val cmpU:  'a t -> 'a t -> ('a -> 'a -> int [@bs]) -> int
 val cmp:  'a t -> 'a t -> ('a -> 'a -> int) -> int
-(** `cmp m1 m2 cmp`
-  First compare by size, if size is the same,
-  compare by key, value pair
-*)
+(** `cmp(m1, m2, cmp)` First compare by size, if size is the same, compare by
+    key, value pair. *)
 
 val eqU: 'a t -> 'a t -> ('a -> 'a -> bool [@bs]) -> bool
 val eq: 'a t -> 'a t -> ('a -> 'a -> bool ) -> bool
-(** `eq m1 m2 cmp` *)
+(** `eq(m1, m2, cmp)` *)
 
 val forEachU: 'a t -> (key -> 'a -> unit [@bs]) ->  unit
 val forEach: 'a t -> (key -> 'a -> unit) ->  unit
-(** `forEach m f` applies `f` to all bindings in map `m`.
-  `f` receives the key as first argument, and the associated value
-  as second argument.
-  The application order of `f`  is in increasing order. *)
+(** `forEach(m, f)` applies `f` to all bindings in map `m`. `f` receives the
+    key as first argument, and the associated value as second argument. The
+    application order of `f` is in increasing order. *)
 
 val reduceU:  'a t -> 'b -> ('b -> key -> 'a -> 'b [@bs]) -> 'b
 val reduce:  'a t -> 'b -> ('b -> key -> 'a -> 'b ) -> 'b
-(** `reduce m a f` computes `(f kN dN ... (f k1 d1 a)...)`,
-  where `k1 ... kN` are the keys of all bindings in `m`
-  (in increasing order), and `d1 ... dN` are the associated data. *)
+(** `reduce(m, a, f), computes`(f(kN, dN) ... (f(k1, d1, a))...)`, where`k1 ...
+    kN`are the keys of all bindings in`m`(in increasing order), and`d1 ... dN`
+    are the associated data. *)
 
 val everyU:  'a t -> (key -> 'a -> bool [@bs]) -> bool
 val every:  'a t -> (key -> 'a -> bool) -> bool
-(** `every m p` checks if all the bindings of the map
-  satisfy the predicate `p`.
-  The application order of `p` is unspecified.
-*)
+(** `every(m, p)` checks if all the bindings of the map satisfy the predicate
+    `p`. The application order of `p` is unspecified. *)
 
 val someU:  'a t -> (key -> 'a -> bool [@bs]) -> bool
 val some:  'a t -> (key -> 'a -> bool) -> bool
-(** `some m p` checks if at least one binding of the map
-  satisfy the predicate `p`.
-  The application order of `p` is unspecified.
-*)
+(** `some(m, p)` checks if at least one binding of the map satisfy the
+    predicate `p`. The application order of `p` is unspecified. *)
 
 
 
@@ -81,7 +81,6 @@ val toList: 'a t -> (key * 'a) list
 (** In increasing order *)
 
 val toArray: 'a t -> (key * 'a) array
-(** In increasing order *)
 
 val fromArray: (key * 'a) array -> 'a t
 val keysToArray: 'a t -> key array
@@ -99,9 +98,7 @@ val getUndefined: 'a t -> key -> 'a Js.undefined
 val getWithDefault:  'a t -> key -> 'a  -> 'a
 val getExn: 'a t -> key -> 'a
 val checkInvariantInternal: _ t -> unit
-(**
-  **raise** when invariant is not held
-*)
+(** Raise when invariant is not held. *)
 
 
 
@@ -110,14 +107,13 @@ val checkInvariantInternal: _ t -> unit
 (*TODO: add functional `merge, partition, keep, split`*)
 
 val remove: 'a t -> key -> unit
-(** `remove m x` do the in-place modification *)
+(** `remove(m, x)` do the in-place modification. *)
 
 val removeMany: 'a t -> key array -> unit
 
 val set: 'a t -> key -> 'a -> unit
-(** `set m x y` do the in-place modification, return
-  `m` for chaining. If `x` was already bound
-  in `m`, its previous binding disappears. *)
+(** `set(m, x, y)` do the in-place modification, return `m` for chaining. If
+    `x` was already bound in `m`, its previous binding disappears. *)
 
 val updateU: 'a t -> key -> ('a option -> 'a option [@bs]) -> unit
 val update: 'a t -> key -> ('a option -> 'a option) -> unit
@@ -125,11 +121,10 @@ val update: 'a t -> key -> ('a option -> 'a option) -> unit
 
 val mapU: 'a t -> ('a -> 'b [@bs]) ->  'b t
 val map: 'a t -> ('a -> 'b) ->  'b t
-(** `map m f` returns a map with same domain as `m`, where the
-  associated value `a` of all bindings of `m` has been
-  replaced by the result of the application of `f` to `a`.
-  The bindings are passed to `f` in increasing order
-  with respect to the ordering over the type of the keys. *)
+(** `map(m, f)` returns a map with same domain as `m`, where the associated
+    value a of all bindings of `m` has been replaced by the result of the
+    application of `f` to `a`. The bindings are passed to `f` in increasing
+    order with respect to the ordering over the type of the keys. *)
 
 val mapWithKeyU: 'a t -> (key -> 'a -> 'b [@bs]) -> 'b t
 val mapWithKey: 'a t -> (key -> 'a -> 'b) -> 'b t