Use markdown instead of ocamldoc for docblock comment (#5095)

- Safe change. Just comments.
- Odoc throws exception for certain snippets; this causes the editor plugin to fail to display the code block. Now we're just gonna pass through the raw markdown block to be displayed.
- More familiar with the JS audience (and most other folks really).

I've converted over:
- `[foo]`
- `@example [{...}]` and miscellaneous  blocks
- `ul`, `ol`
- `{b boldStuff}`
- `{i italicStuff}`
- `{%html}` blocks
- Things that don't need escape anymore, e.g. `\[\@\@module\]`
- `@return` -> `**return**`. Same for `@param`, `@raise` and `@since`.
- Use markdown link for `@see`.
- 2 indentations instead of 4, since 4 means a code block in markdown.
- Double newline for a rendered newline (markdown single newline doesn't break line in output).

Author: chenglou

jscomp/main/builtin_cmi_datasets.ml

@@ -24,244 +24,242 @@
 
 (** A stdlib shipped with ReScript
 
-    This stdlib is still in {i beta} but we encourage you to try it out and
-    give us feedback.
+  This stdlib is still in _beta_ but we encourage you to try it out and
+  give us feedback.
 
-    {b Motivation }
+  **Motivation**
 
-    The motivation for creating such library is to provide ReScript users a
-    better end-to-end user experience, since the original OCaml stdlib was not
-    written with JS in mind. Below is a list of areas this lib aims to
-    improve:
-    {ol
-    {- Consistency in name convention: camlCase, and arguments order}
-    {- Exception thrown functions are all suffixed with {i Exn}, e.g, {i getExn}}
-    {- Better performance and smaller code size running on JS platform}
-    }
+  The motivation for creating such library is to provide ReScript users a
+  better end-to-end user experience, since the original OCaml stdlib was not
+  written with JS in mind. Below is a list of areas this lib aims to
+  improve:
+  1. Consistency in name convention: camlCase, and arguments order
+  2. Exception thrown functions are all suffixed with _Exn_, e.g, _getExn_
+  3. Better performance and smaller code size running on JS platform
 
-    {b Name Convention}
+  **Name Convention**
 
-    For higher order functions, it will be suffixed {b U} if it takes uncurried
-    callback.
+  For higher order functions, it will be suffixed **U** if it takes uncurried
+  callback.
 
-    {[
-      val forEach  : 'a t -> ('a -> unit) -> unit
-      val forEachU : 'a t -> ('a -> unit [\@bs]) -> unit
-    ]}
+  ```
+  val forEach  : 'a t -> ('a -> unit) -> unit
+  val forEachU : 'a t -> ('a -> unit [@bs]) -> unit
+  ```
 
-    In general, uncurried version will be faster, but it may be less familiar to
-    people who have a background in functional programming.
+  In general, uncurried version will be faster, but it may be less familiar to
+  people who have a background in functional programming.
 
-   {b A special encoding for collection safety}
+   **A special encoding for collection safety**
 
    When we create a collection library for a custom data type we need a way to provide a comparator
-   function. Take {i Set} for example, suppose its element type is a pair of ints,
-    it needs a custom {i compare} function that takes two tuples and returns their order.
-    The {i Set} could not just be typed as [ Set.t (int * int) ], its customized {i compare} function
-    needs to manifest itself in the signature, otherwise, if the user creates another
-    customized {i compare} function, the two collection could mix which would result in runtime error.
-
-    The original OCaml stdlib solved the problem using {i functor} which creates a big
-    closure at runtime and makes dead code elimination much harder.
-    We use a phantom type to solve the problem:
-
-    {[
-      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 [mySet1] and [mySet2] having different type, so
-    e.g. a `merge` operation that tries to merge these two sets will correctly fail.
-
-    {[
-      val mySet1 : ((int * int), Comparable1.identity) t
-      val mySet2 : ((int * int), Comparable2.identity) t
-    ]}
-
-    [Comparable1.identity] and [Comparable2.identity] are not the same using our encoding scheme.
-
-    {b Collection Hierarchy}
-
-    In general, we provide a generic collection module, but also create specialized
-    modules for commonly used data type. Take {i Belt.Set} for example, we provide:
-
-    {[
-        Belt.Set
-        Belt.Set.Int
-        Belt.Set.String
-    ]}
-
-    The specialized modules {i Belt.Set.Int}, {i Belt.Set.String} are in general more
-    efficient.
-
-    Currently, both {i Belt_Set} and {i Belt.Set} are accessible to users for some
-    technical reasons,
-    we {b strongly recommend} users stick to qualified import, {i Belt.Set}, we may hide
-    the internal, {i i.e}, {i Belt_Set} in the future
+   function. Take _Set_ for example, suppose its element type is a pair of ints,
+  it needs a custom _compare_ function that takes two tuples and returns their order.
+  The _Set_ could not just be typed as `Set.t (int * int)`, its customized _compare_ function
+  needs to manifest itself in the signature, otherwise, if the user creates another
+  customized _compare_ function, the two collection could mix which would result in runtime error.
+
+  The original OCaml stdlib solved the problem using _functor_ which creates a big
+  closure at runtime and makes dead code elimination much harder.
+  We use a phantom type to solve the problem:
+
+  ```
+  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 `mySet1` and `mySet2` having different type, so
+  e.g. a `merge` operation that tries to merge these two sets will correctly fail.
+
+  ```
+  val mySet1 : ((int * int), Comparable1.identity) t
+  val mySet2 : ((int * int), Comparable2.identity) t
+  ```
+
+  `Comparable1.identity` and `Comparable2.identity` are not the same using our encoding scheme.
+
+  **Collection Hierarchy**
+
+  In general, we provide a generic collection module, but also create specialized
+  modules for commonly used data type. Take _Belt.Set_ for example, we provide:
+
+  ```
+  Belt.Set
+  Belt.Set.Int
+  Belt.Set.String
+  ```
+
+  The specialized modules _Belt.Set.Int_, _Belt.Set.String_ are in general more
+  efficient.
+
+  Currently, both _Belt_Set_ and _Belt.Set_ are accessible to users for some
+  technical reasons,
+  we **strongly recommend** users stick to qualified import, _Belt.Set_, we may hide
+  the internal, _i.e_, _Belt_Set_ in the future
 
 *)
 
 [@@@warning "-49"]
 
-(** {!Belt.Id}
+(** [`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
-    comparison functions won't mix
+  It create a unique identifier per module of
+  functions so that different data structures with slightly different
+  comparison functions won't mix
 *)
 module Id = Belt_Id
 
-(** {!Belt.Array}
+(** [`Belt.Array`]()
 
-    {b mutable array}: Utilities functions
+  **mutable array**: Utilities functions
 *)
 module Array = Belt_Array
 
-(** {!Belt.SortArray}
+(** [`Belt.SortArray`]()
 
-    The top level provides some generic sort related utilities.
+  The top level provides some generic sort related utilities.
 
-    It also has two specialized inner modules
-    {!Belt.SortArray.Int} and {!Belt.SortArray.String}
+  It also has two specialized inner modules
+  [`Belt.SortArray.Int`]() and [`Belt.SortArray.String`]()
 *)
 module SortArray = Belt_SortArray
 
-(** {!Belt.MutableQueue}
+(** [`Belt.MutableQueue`]()
 
-    An FIFO(first in first out) queue data structure
+  An FIFO(first in first out) queue data structure
 *)
 module MutableQueue = Belt_MutableQueue
 
-(** {!Belt.MutableStack}
+(** [`Belt.MutableStack`]()
 
-    An FILO(first in last out) stack data structure
+  An FILO(first in last out) stack data structure
 *)
 module MutableStack = Belt_MutableStack
 
-(** {!Belt.List}
+(** [`Belt.List`]()
 
-    Utilities for List data type
+  Utilities for List data type
 *)
 module List = Belt_List
 
-(** {!Belt.Range}
+(** [`Belt.Range`]()
 
-    Utilities for a closed range [(from, start)]
+  Utilities for a closed range `(from, start)`
 *)
 module Range = Belt_Range
 
-(** {!Belt.Set}
+(** [`Belt.Set`]()
 
-    The top level provides generic {b immutable} set operations.
+  The top level provides generic **immutable** set operations.
 
-    It also has three specialized inner modules
-    {!Belt.Set.Int}, {!Belt.Set.String} and
+  It also has three specialized inner modules
+  [`Belt.Set.Int`](), [`Belt.Set.String`]() and
 
-    {!Belt.Set.Dict}: This module separates data from function
-    which is more verbose but slightly more efficient
+  [`Belt.Set.Dict`](): This module separates data from function
+  which is more verbose but slightly more efficient
 
 *)
 module Set = Belt_Set
 
 
-(** {!Belt.Map},
+(** [`Belt.Map`](),
 
-    The top level provides generic {b immutable} map operations.
+  The top level provides generic **immutable** map operations.
 
-    It also has three specialized inner modules
-    {!Belt.Map.Int}, {!Belt.Map.String} and
+  It also has three specialized inner modules
+  [`Belt.Map.Int`](), [`Belt.Map.String`]() and
 
-    {!Belt.Map.Dict}: This module separates data from function
-    which  is more verbose but slightly more efficient
+  [`Belt.Map.Dict`](): This module separates data from function
+  which  is more verbose but slightly more efficient
 *)
 module Map = Belt_Map
 
 
-(** {!Belt.MutableSet}
+(** [`Belt.MutableSet`]()
 
-    The top level provides generic {b mutable} set operations.
+  The top level provides generic **mutable** set operations.
 
-    It also has two specialized inner modules
-    {!Belt.MutableSet.Int} and {!Belt.MutableSet.String}
+  It also has two specialized inner modules
+  [`Belt.MutableSet.Int`]() and [`Belt.MutableSet.String`]()
 *)
 module MutableSet = Belt_MutableSet
 
-(** {!Belt.MutableMap}
+(** [`Belt.MutableMap`]()
 
-    The top level provides generic {b mutable} map operations.
+  The top level provides generic **mutable** map operations.
 
-    It also has two specialized inner modules
-    {!Belt.MutableMap.Int} and {!Belt.MutableMap.String}
+  It also has two specialized inner modules
+  [`Belt.MutableMap.Int`]() and [`Belt.MutableMap.String`]()
 
 *)
 module MutableMap = Belt_MutableMap
 
 
-(** {!Belt.HashSet}
+(** [`Belt.HashSet`]()
 
-    The top level provides generic {b mutable} hash set operations.
+  The top level provides generic **mutable** hash set operations.
 
-    It also has two specialized inner modules
-    {!Belt.HashSet.Int} and {!Belt.HashSet.String}
+  It also has two specialized inner modules
+  [`Belt.HashSet.Int`]() and [`Belt.HashSet.String`]()
 *)
 module HashSet = Belt_HashSet
 
 
-(** {!Belt.HashMap}
+(** [`Belt.HashMap`]()
 
-    The top level provides generic {b mutable} hash map operations.
+  The top level provides generic **mutable** hash map operations.
 
-    It also has two specialized inner modules
-    {!Belt.HashMap.Int} and {!Belt.HashMap.String}
+  It also has two specialized inner modules
+  [`Belt.HashMap.Int`]() and [`Belt.HashMap.String`]()
 *)
 module HashMap = Belt_HashMap
 
 
-(** {!Belt.Option}
+(** [`Belt.Option`]()
 
-    Utilities for option data type.
+  Utilities for option data type.
 *)
 module Option = Belt_Option
 
 
-(** {!Belt.Result}
+(** [`Belt.Result`]()
 
-    Utilities for result data type.
+  Utilities for result data type.
 *)
 
 module Result = Belt_Result
 
-(** {!Belt.Int}
+(** [`Belt.Int`]()
 
-    Utilities for Int.
+  Utilities for Int.
 *)
 
 module Int = Belt_Int
 
 
-(** {!Belt.Float}
+(** [`Belt.Float`]()
 
-    Utilities for Float.
+  Utilities for Float.
 *)
 
 module Float = Belt_Float

jscomp/main/builtin_cmj_datasets.ml

@@ -232,7 +232,7 @@ let blitUnsafe ~src:a1  ~srcOffset:srcofs1 ~dst:a2 ~dstOffset:srcofs2 ~len:blitL
       a2.!(j + srcofs2) <-  a1.!(j + srcofs1)
     done
 
-(* We don't need check [blitLength] since when [blitLength < 0] the
+(* We don't need check `blitLength` since when `blitLength < 0` the
    for loop will be nop
 *)
 let blit ~src:a1 ~srcOffset:ofs1 ~dst:a2 ~dstOffset:ofs2 ~len =