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 =