[Docs][Belt] Cleanup; remove references to comparableU (#2618)

This is a first round of cleanup. It fixes typos, removes redundant (and
sometimes wrong) examples and rewords a few things. This reduces the
verbosity of pages like Set and Map, where lots of helpers repeated the
creation of e.g. IntCmp, which becomes verbose after a few times.

Later I'll be properly sectionning each page too, just like how stdlib
docs have section in List for e.g. "list scanning", "iterators", etc.

Author: chenglou

jscomp/others/belt.ml

@@ -1,5 +1,5 @@
 (* Copyright (C) 2015-2016 Bloomberg Finance L.P.
- * 
+ *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU Lesser General Public License as published by
  * the Free Software Foundation, either version 3 of the License, or
@@ -17,22 +17,22 @@
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU Lesser General Public License for more details.
- * 
+ *
  * You should have received a copy of the GNU Lesser General Public License
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *)
 
 
-(** A stdlib shipped with BuckleScript 
+(** A stdlib shipped with BuckleScript
 
-    This stdlib is still in {i beta} status, but we encourage you to try it out and 
+    This stdlib is still in {i beta} status, but we encourage you to try it out and
     provide feedback.
 
     {b Motivation }
 
-    The motivation of creating such library is to provide BuckleScript users a 
-    better end-to-end user experience, since the original OCaml stdlib was not 
-    written with JS platform in mind, below are a list of areas this lib aims to 
+    The motivation of creating such library is to provide BuckleScript users a
+    better end-to-end user experience, since the original OCaml stdlib was not
+    written with JS platform in mind, below are a list of areas this lib aims to
     improve: {ol
     {- 1. Consistency in name convention: camlCase, and arguments order}
     {- 2. Exception thrown functions are all suffixed with {i Exn}, e.g, {i getExn}}
@@ -55,7 +55,7 @@
    {b A special encoding for collection safety}
 
    When we create a collection library for a custom data type, take {i Set} for
-   example, suppose its element type is a pair of ints, 
+   example, suppose its element type is a pair of ints,
     it needs a custom {i compare} function. However, the {i Set} could not
     just be typed as [ Set.t (int * int) ],
     its customized {i compare} function needs to be
@@ -68,32 +68,36 @@
     We introduced a phantom type to solve the problem
 
     {[
-      type t = int * int 
-      module I0 =
-        (val Belt.Id.comparableU (fun[\@bs] ((a0,a1) : t) ((b0,b1) : t) ->
-             match compare a0 b0 with
-             | 0 -> compare a1 b1
-             | c -> c 
-           ))
-    let s0 = Belt.Set.make ~id:(module I0)
-    module I1 =
-      (val Belt.Id.comparableU (fun[\@bs] ((a0,a1) : t) ((b0,b1) : t) ->
-           match compare a1 b1 with
-           | 0 -> compare a0 b0
-           | c -> c 
-         ))
-    let s1 = Belt.Set.make ~id:(module I1)
+      module Comparable1 = 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 mySet1 = Belt.Set.make ~id:(module Comparable1)
+
+    module Comparable2 = 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 mySet2 = Belt.Set.make ~id:(module Comparable2)
     ]}
 
-    Here the compiler would infer [s0] and [s1] having different type so that
-    it would not mix.
+    Here, the compiler would infer [mySet1] and [mySet2] having different type, so
+    e.g. a `merge` operation that tries to merge these two sets will correctly fail.
 
     {[
-      val s0 : ((int * int), I0.identity) t
-      val s1 : ((int * int), I1.identity) t
+      val mySet1 : ((int * int), Comparable1.identity) t
+      val mySet2 : ((int * int), Comparable2.identity) t
     ]}
 
-    [I0.identity] and [I1.identity] are not the same using our encoding scheme.
+    [Comparable1.identity] and [Comparable2.identity] are not the same using our encoding scheme.
 
     {b Collection Hierarchy}
 
@@ -113,16 +117,16 @@
     technical reasons,
     we {b strongly recommend} users stick to qualified import, {i Belt.Sort}, we may hide
     the internal, {i i.e}, {i Belt_Set} in the future
-    
+
 *)
 
 (** {!Belt.Id}
 
-    Provide utilities to create identified comparators or hashes for 
-    data structures used below. 
-    
+    Provide utilities to create identified comparators or hashes for
+    data structures used below.
+
     It create a unique identifier per module of
-    functions so that different data structures with slightly different 
+    functions so that different data structures with slightly different
     comparison functions won't mix
 *)
 module Id = Belt_Id
@@ -134,34 +138,34 @@ module Id = Belt_Id
 module Array = Belt_Array
 
 (** {!Belt.SortArray}
-    
+
     The top level provides some generic sort related utilities.
-    
+
     It also has two specialized inner modules
     {!Belt.SortArray.Int} and {!Belt.SortArray.String}
 *)
 module SortArray = Belt_SortArray
 
 (** {!Belt.MutableQueue}
-    
+
     An FIFO(first in first out) queue data structure
 *)
 module MutableQueue = Belt_MutableQueue
 
 (** {!Belt.MutableStack}
-    
+
     An FILO(first in last out) stack data structure
 *)
-module MutableStack = Belt_MutableStack 
+module MutableStack = Belt_MutableStack
 
 (** {!Belt.List}
-    
+
     Utilities for List data type
 *)
 module List = Belt_List
 
 (** {!Belt.Range}
-    
+
     Utilities for a closed range [(from, start)]
 *)
 module Range = Belt_Range
@@ -183,29 +187,29 @@ module Set = Belt_Set
 (** {!Belt.Map},
 
     The top level provides generic {b immutable} map operations.
-    
+
     It also has three specialized inner modules
     {!Belt.Map.Int} and {!Belt.Map.String}
 
     {!Belt.Map.Dict}: This module separate date from function
     which  is more verbose but slightly more efficient
-*)    
+*)
 module Map = Belt_Map
 
 
 (** {!Belt.MutableSet}
-    
+
     The top level provides generic {b mutable} set operations.
-    
+
     It also has two specialized inner modules
     {!Belt.MutableSet.Int} and {!Belt.MutableSet.String}
 *)
 module MutableSet = Belt_MutableSet
 
 (** {!Belt.MutableMap}
-    
+
     The top level provides generic {b mutable} map operations.
-    
+
     It also has two specialized inner modules
     {!Belt.MutableMap.Int} and {!Belt.MutableMap.String}
 
@@ -214,24 +218,24 @@ module MutableMap = Belt_MutableMap
 
 
 (** {!Belt.HashSet}
-    
+
     The top level provides generic {b mutable} hash set operations.
-    
+
     It also has two specialized inner modules
     {!Belt.HashSet.Int} and {!Belt.HashSet.String}
 *)
 module HashSet = Belt_HashSet
 
 
 (** {!Belt.HashMap}
-    
+
     The top level provides generic {b mutable} hash map operations.
-    
+
     It also has two specialized inner modules
     {!Belt.HashMap.Int} and {!Belt.HashMap.String}
 *)
 module HashMap = Belt_HashMap
-  
+