From 9e13d5a636f5ea2be8fb262214ee3c360e555724 Mon Sep 17 00:00:00 2001
From: Christoph Knittel <ck@cca.io>
Date: Thu, 4 Jul 2024 20:57:11 +0200
Subject: [PATCH 1/2] Check in changes after make lib

---
 jscomp/others/belt_HashSetInt.resi    | 8 ++++----
 jscomp/others/belt_HashSetString.resi | 8 ++++----
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/jscomp/others/belt_HashSetInt.resi b/jscomp/others/belt_HashSetInt.resi
index 05325e845a..85a7e6e541 100644
--- a/jscomp/others/belt_HashSetInt.resi
+++ b/jscomp/others/belt_HashSetInt.resi
@@ -23,12 +23,12 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
 
 /***
-This module is [`Belt.HashSet`]() specialized with key type to be a primitive type.
+  This module is [`Belt.HashSet`]() specialized with key type to be a primitive type.
 
-It is more efficient in general, the  API is the same with [`Belt.HashSet`]() except its key type is fixed,
-and identity is not needed(using the built-in one)
+  It is more efficient in general, the  API is the same with [`Belt.HashSet`]() except its key type is fixed,
+  and identity is not needed(using the built-in one)
 
-**See** [`Belt.HashSet`]()
+  **See** [`Belt.HashSet`]()
 */
 
 type key = int
diff --git a/jscomp/others/belt_HashSetString.resi b/jscomp/others/belt_HashSetString.resi
index 3c2532f418..bbe2617b3f 100644
--- a/jscomp/others/belt_HashSetString.resi
+++ b/jscomp/others/belt_HashSetString.resi
@@ -23,12 +23,12 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
 
 /***
-This module is [`Belt.HashSet`]() specialized with key type to be a primitive type.
+  This module is [`Belt.HashSet`]() specialized with key type to be a primitive type.
 
-It is more efficient in general, the  API is the same with [`Belt.HashSet`]() except its key type is fixed,
-and identity is not needed(using the built-in one)
+  It is more efficient in general, the  API is the same with [`Belt.HashSet`]() except its key type is fixed,
+  and identity is not needed(using the built-in one)
 
-**See** [`Belt.HashSet`]()
+  **See** [`Belt.HashSet`]()
 */
 
 type key = string

From 66897087b855b4b72cca7dfb92e3ea2f48533a5c Mon Sep 17 00:00:00 2001
From: Christoph Knittel <ck@cca.io>
Date: Thu, 4 Jul 2024 20:37:58 +0200
Subject: [PATCH 2/2] Fix doc comments (no @ocaml.*)

---
 jscomp/others/js.res           | 136 +++++++++---------
 jscomp/others/js_math.res      | 246 ++++++++++++++++-----------------
 jscomp/others/js_string.res    |  38 ++---
 jscomp/runtime/caml_format.res |   4 +-
 jscomp/runtime/js.res          | 205 ++++++++++++++++-----------
 5 files changed, 333 insertions(+), 296 deletions(-)

diff --git a/jscomp/others/js.res b/jscomp/others/js.res
index 8413f30f44..0fde2dfea2 100644
--- a/jscomp/others/js.res
+++ b/jscomp/others/js.res
@@ -23,14 +23,15 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
 
 @@config({flags: ["-unboxed-types", "-w", "-49"]})
-@@ocaml.text(/* DESIGN:
+
+/* DESIGN:
    - It does not have any code, all its code will be inlined so that
        there will never be
    {[ require('js')]}
    - Its interface should be minimal
 */
 
-"
+/***
 The Js module mostly contains ReScript bindings to _standard JavaScript APIs_
 like [console.log](https://developer.mozilla.org/en-US/docs/Web/API/Console/log),
 or the JavaScript
@@ -71,9 +72,9 @@ Js.log(Js.String.startsWith(\"Re\", \"ReScript\"))
 ## Js.Xxx2 Modules
 
 Prefer `Js.Array2` over `Js.Array`, `Js.String2` over `Js.String`, etc. The latters are old modules.
-")
+ */
 
-@ocaml.doc(" JS object type ")
+/** JS object type */
 type t<'a> = {..} as 'a
 
 module MapperRt = Js_mapperRt
@@ -86,24 +87,22 @@ module Internal = {
   external opaque: 'a => 'a = "%opaque"
 }
 
-@@ocaml.text("/*")
-
-@ocaml.doc("
+/**
   Nullable value of this type can be either null or 'a. This type is equivalent to Js.Null.t.
-")
+*/
 @unboxed
 type null<+'a> = Value('a) | @as(null) Null
 
-@ocaml.doc("
+/**
   A value of this type can be either undefined or 'a. This type is equivalent to Js.Undefined.t.
-")
+*/
 type undefined<+'a>
 
 @unboxed type nullable<+'a> = Value('a) | @as(null) Null | @as(undefined) Undefined
 
-@@ocaml.text("
+/***
   A value of this type can be undefined, null or 'a. This type is equivalent to Js.Null_undefined.t.
-")
+*/
 
 type null_undefined<+'a> = nullable<'a>
 
@@ -113,31 +112,31 @@ external nullToOption: null<'a> => option<'a> = "#null_to_opt"
 external isNullable: nullable<'a> => bool = "#is_nullable"
 external import: 'a => promise<'a> = "#import"
 
-@ocaml.doc(" The same as {!test} except that it is more permissive on the types of input ")
+/** The same as {!test} except that it is more permissive on the types of input */
 external testAny: 'a => bool = "#is_nullable"
 
-@ocaml.doc("
+/**
   The promise type, defined here for interoperation across packages.
-")
+*/
 type promise<+'a, +'e>
 
-@ocaml.doc("
+/**
   The same as empty in `Js.Null`. Compiles to `null`.
-")
+*/
 external null: null<'a> = "#null"
 
-@ocaml.doc("
+/**
   The same as empty `Js.Undefined`. Compiles to `undefined`.
-")
+*/
 external undefined: undefined<'a> = "#undefined"
 
-@ocaml.doc("
+/**
 `typeof x` will be compiled as `typeof x` in JS. Please consider functions in
 `Js.Types` for a type safe way of reflection.
-")
+*/
 external typeof: 'a => string = "#typeof"
 
-@val @scope("console") @ocaml.doc(" Equivalent to console.log any value. ")
+@val @scope("console") /** Equivalent to console.log any value. */
 external log: 'a => unit = "log"
 
 @val @scope("console") external log2: ('a, 'b) => unit = "log"
@@ -145,145 +144,142 @@ external log: 'a => unit = "log"
 
 @val @scope("console") external log4: ('a, 'b, 'c, 'd) => unit = "log"
 
-@val
-@scope("console")
-@variadic
-@ocaml.doc(" A convenience function to console.log more than 4 arguments ")
+@val @scope("console") @variadic /** A convenience function to console.log more than 4 arguments */
 external logMany: array<'a> => unit = "log"
 
 external eqNull: ('a, null<'a>) => bool = "%bs_equal_null"
 external eqUndefined: ('a, undefined<'a>) => bool = "%bs_equal_undefined"
 external eqNullable: ('a, nullable<'a>) => bool = "%bs_equal_nullable"
 
-@@ocaml.text(" ## Operators ")
+/* ## Operators */
 
-@ocaml.doc("
+/**
    `unsafe_lt(a, b)` will be compiled as `a < b`.
     It is marked as unsafe, since it is impossible
     to give a proper semantics for comparision which applies to any type
-")
+*/
 external unsafe_lt: ('a, 'a) => bool = "#unsafe_lt"
 
-@ocaml.doc("
+/**
    `unsafe_le(a, b)` will be compiled as `a <= b`.
    See also `Js.unsafe_lt`.
-")
+*/
 external unsafe_le: ('a, 'a) => bool = "#unsafe_le"
 
-@ocaml.doc("
+/**
    `unsafe_gt(a, b)` will be compiled as `a > b`.
     See also `Js.unsafe_lt`.
-")
+*/
 external unsafe_gt: ('a, 'a) => bool = "#unsafe_gt"
 
-@ocaml.doc("
+/**
    `unsafe_ge(a, b)` will be compiled as `a >= b`.
    See also `Js.unsafe_lt`.
-")
+*/
 external unsafe_ge: ('a, 'a) => bool = "#unsafe_ge"
 
-@@ocaml.text(" ## Nested Modules ")
+/* ## Nested Modules */
 
-@ocaml.doc(" Provide utilities for `Js.null<'a>` ")
+/** Provide utilities for `Js.null<'a>` */
 module Null = Js_null
 
-@ocaml.doc(" Provide utilities for `Js.undefined<'a>` ")
+/** Provide utilities for `Js.undefined<'a>` */
 module Undefined = Js_undefined
 
-@ocaml.doc(" Provide utilities for `Js.null_undefined` ")
+/** Provide utilities for `Js.null_undefined` */
 module Nullable = Js_null_undefined
 
 module Null_undefined = Js_null_undefined
 
-@ocaml.doc(" Provide utilities for dealing with Js exceptions ")
+/** Provide utilities for dealing with Js exceptions */
 module Exn = Js_exn
 
-@ocaml.doc(" Provide bindings to JS array")
+/** Provide bindings to JS array*/
 module Array = Js_array
 
-@ocaml.doc(" Provide bindings to JS array")
+/** Provide bindings to JS array*/
 module Array2 = Js_array2
 
-@ocaml.doc(" Provide bindings to JS string ")
+/** Provide bindings to JS string */
 module String = Js_string
 
-@ocaml.doc(" Provide bindings to JS string ")
+/** Provide bindings to JS string */
 module String2 = Js_string2
 
-@ocaml.doc(" Provide bindings to JS regex expression ")
+/** Provide bindings to JS regex expression */
 module Re = Js_re
 
-@ocaml.doc(" Provide bindings to JS Promise ")
+/** Provide bindings to JS Promise */
 module Promise = Js_promise
 
-@ocaml.doc(" Provide bindings to JS Promise ")
+/** Provide bindings to JS Promise */
 module Promise2 = Js_promise2
 
-@ocaml.doc(" Provide bindings for JS Date ")
+/** Provide bindings for JS Date */
 module Date = Js_date
 
-@ocaml.doc(" Provide utilities for JS dictionary object ")
+/** Provide utilities for JS dictionary object */
 module Dict = Js_dict
 
-@ocaml.doc(" Provide bindings to JS global functions in global namespace")
+/** Provide bindings to JS global functions in global namespace*/
 module Global = Js_global
 
-@ocaml.doc(" Provide utilities for json ")
+/** Provide utilities for json */
 module Json = Js_json
 
-@ocaml.doc(" Provide bindings for JS `Math` object ")
+/** Provide bindings for JS `Math` object */
 module Math = Js_math
 
-@ocaml.doc(" Provide utilities for `Js.t` ")
+/** Provide utilities for `Js.t` */
 module Obj = Js_obj
 
-@ocaml.doc(" Provide bindings for JS typed array ")
+/** Provide bindings for JS typed array */
 module Typed_array = Js_typed_array
 
-@ocaml.doc(" Provide bindings for JS typed array ")
+/** Provide bindings for JS typed array */
 module TypedArray2 = Js_typed_array2
 
-@ocaml.doc(" Provide utilities for manipulating JS types  ")
+/** Provide utilities for manipulating JS types  */
 module Types = Js_types
 
-@ocaml.doc(" Provide utilities for JS float ")
+/** Provide utilities for JS float */
 module Float = Js_float
 
-@ocaml.doc(" Provide utilities for int ")
+/** Provide utilities for int */
 module Int = Js_int
 
-@ocaml.doc(" Provide utilities for bigint ")
+/** Provide utilities for bigint */
 module BigInt = Js_bigint
 
-@ocaml.doc(" Provide utilities for File ")
+/** Provide utilities for File */
 module File = Js_file
 
-@ocaml.doc(" Provide utilities for Blob ")
+/** Provide utilities for Blob */
 module Blob = Js_blob
 
-@ocaml.doc(" Provide utilities for option ")
+/** Provide utilities for option */
 module Option = Js_option
 
-@ocaml.doc(" Define the interface for result ")
+/** Define the interface for result */
 module Result = Js_result
 
-@ocaml.doc(" Provide utilities for list ")
+/** Provide utilities for list */
 module List = Js_list
 
-@ocaml.doc(" Provides bindings for JS Vector ")
+/** Provides bindings for JS Vector */
 module Vector = Js_vector
 
-@ocaml.doc(" Provides bindings for console ")
+/** Provides bindings for console */
 module Console = Js_console
 
-@ocaml.doc(" Provides bindings for ES6 Set ")
+/** Provides bindings for ES6 Set */
 module Set = Js_set
 
-@ocaml.doc(" Provides bindings for ES6 WeakSet ")
+/** Provides bindings for ES6 WeakSet */
 module WeakSet = Js_weakset
 
-@ocaml.doc(" Provides bindings for ES6 Map ")
+/** Provides bindings for ES6 Map */
 module Map = Js_map
 
-@ocaml.doc(" Provides bindings for ES6 WeakMap ")
+/** Provides bindings for ES6 WeakMap */
 module WeakMap = Js_weakmap
diff --git a/jscomp/others/js_math.res b/jscomp/others/js_math.res
index 23c2e3b387..15e5649cba 100644
--- a/jscomp/others/js_math.res
+++ b/jscomp/others/js_math.res
@@ -1,4 +1,4 @@
-@@ocaml.text(/* Copyright (C) 2015-2016 Bloomberg Finance L.P.
+/* 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
@@ -22,165 +22,165 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
 
-"
+/***
 Provide utilities for JS Math. Note: The constants `_E`, `_LN10`, `_LN2`,
 `_LOG10E`, `_LOG2E`, `_PI`, `_SQRT1_2`, and `_SQRT2` begin with an underscore
 because ReScript variable names cannot begin with a capital letter. (Module
 names begin with upper case.)
-")
+*/
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Euler's number; ≈ 2.718281828459045. See
 [`Math.E`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/E)
 on MDN.
-")
+*/
 external _E: float = "E"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Natural logarithm of 2; ≈ 0.6931471805599453. See
 [`Math.LN2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/LN2)
 on MDN.
-")
+*/
 external _LN2: float = "LN2"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Natural logarithm of 10; ≈ 2.302585092994046. See
 [`Math.LN10`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/LN10)
 on MDN.
-")
+*/
 external _LN10: float = "LN10"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Base 2 logarithm of E; ≈ 1.4426950408889634. See
 [`Math.LOG2E`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/LOG2E)
 on MDN.
-")
+*/
 external _LOG2E: float = "LOG2E"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Base 10 logarithm of E; ≈ 0.4342944819032518. See
 [`Math.LOG10E`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/LOG10E)
 on MDN.
-")
+*/
 external _LOG10E: float = "LOG10E"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Pi - ratio of the circumference to the diameter of a circle; ≈ 3.141592653589793. See
 [`Math.PI`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/PI)
 on MDN.
-")
+*/
 external _PI: float = "PI"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Square root of 1/2; ≈ 0.7071067811865476. See
 [`Math.SQRT1_2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/SQRT1_2)
 on MDN.
-")
+*/
 external _SQRT1_2: float = "SQRT1_2"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Square root of 2; ≈ 1.4142135623730951. See
 [`Math.SQRT2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/SQRT2)
 on MDN.
-")
+*/
 external _SQRT2: float = "SQRT2"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Absolute value for integer argument. See
 [`Math.abs`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/abs)
 on MDN.
-")
+*/
 external abs_int: int => int = "abs"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Absolute value for float argument. See
 [`Math.abs`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/abs)
 on MDN.
-")
+*/
 external abs_float: float => float = "abs"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Arccosine (in radians) of argument; returns `NaN` if the argument is outside
 the range [-1.0, 1.0]. See
 [`Math.acos`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/acos)
 on MDN.
-")
+*/
 external acos: float => float = "acos"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Hyperbolic arccosine (in radians) of argument; returns `NaN` if the argument
 is less than 1.0. See
 [`Math.acosh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/acosh)
 on MDN.
-")
+*/
 external acosh: float => float = "acosh"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Arcsine (in radians) of argument; returns `NaN` if the argument is outside
 the range [-1.0, 1.0]. See
 [`Math.asin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/asin)
 on MDN.
-")
+*/
 external asin: float => float = "asin"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Hyperbolic arcsine (in radians) of argument. See
 [`Math.asinh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/asinh)
 on MDN.
-")
+*/
 external asinh: float => float = "asinh"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Arctangent (in radians) of argument. See
 [`Math.atan`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/atan)
 on MDN.
-")
+*/
 external atan: float => float = "atan"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Hyperbolic arctangent (in radians) of argument; returns `NaN` if the argument
 is is outside the range [-1.0, 1.0]. Returns `-Infinity` and `Infinity` for
 arguments -1.0 and 1.0. See
 [`Math.atanh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/atanh)
 on MDN.
-")
+*/
 external atanh: float => float = "atanh"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the angle (in radians) of the quotient `y /. x`. It is also the angle
 between the *x*-axis and point (*x*, *y*). See
 [`Math.atan2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/atan2)
@@ -195,21 +195,21 @@ Js.Math.atan2(~x=-5.0, ~y=5.0, ())
 Js.Math.atan2(~x=-5.0, ~y=5.0, ()) == 3.0 *. Js.Math._PI /. 4.0
 Js.Math.atan2(~x=-0.0, ~y=-5.0, ()) == -.Js.Math._PI /. 2.0
 ```
-")
+*/
 external atan2: (~y: float, ~x: float, unit) => float = "atan2"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Cube root. See
 [`Math.cbrt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cbrt)
 on MDN
-")
+*/
 external cbrt: float => float = "cbrt"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the smallest integer greater than or equal to the argument. This
 function may return values not representable by `int`, whose range is
 -2147483648 to 2147483647. This is because, in JavaScript, there are only
@@ -226,12 +226,12 @@ Js.Math.unsafe_ceil_int(3.0) == 3
 Js.Math.unsafe_ceil_int(-3.1) == -3
 Js.Math.unsafe_ceil_int(1.0e15) // result is outside range of int datatype
 ```
-")
+*/
 external unsafe_ceil_int: float => int = "ceil"
 
 @deprecated("Please use `unsafe_ceil_int` instead") let unsafe_ceil = unsafe_ceil_int
 
-@ocaml.doc("
+/**
 Returns the smallest `int` greater than or equal to the argument; the result
 is pinned to the range of the `int` data type: -2147483648 to 2147483647. See
 [`Math.ceil`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil)
@@ -246,7 +246,7 @@ Js.Math.ceil_int(-3.1) == -3
 Js.Math.ceil_int(-1.0e15) == -2147483648
 Js.Math.ceil_int(1.0e15) == 2147483647
 ```
-")
+*/
 let ceil_int = (f: float): int =>
   if f > Js_int.toFloat(Js_int.max) {
     Js_int.max
@@ -260,7 +260,7 @@ let ceil_int = (f: float): int =>
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the smallest integral value greater than or equal to the argument.
 The result is a `float` and is not restricted to the `int` data type range.
 See
@@ -275,12 +275,12 @@ Js.Math.ceil_float(3.0) == 3.0
 Js.Math.ceil_float(-3.1) == -3.0
 Js.Math.ceil_float(2_150_000_000.3) == 2_150_000_001.0
 ```
-")
+*/
 external ceil_float: float => float = "ceil"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Number of leading zero bits of the argument's 32 bit int representation. See
 [`Math.clz32`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/clz32)
 on MDN.
@@ -292,50 +292,50 @@ Js.Math.clz32(0) == 32
 Js.Math.clz32(-1) == 0
 Js.Math.clz32(255) == 24
 ```
-")
+*/
 external clz32: int => int = "clz32"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Cosine of argument, which must be specified in radians. See
 [`Math.cos`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cos)
 on MDN.
-")
+*/
 external cos: float => float = "cos"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Hyperbolic cosine of argument, which must be specified in radians. See
 [`Math.cosh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cosh)
 on MDN.
-")
+*/
 external cosh: float => float = "cosh"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Natural exponentional; returns *e* (the base of natural logarithms) to the
 power of the given argument. See
 [`Math.exp`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/exp)
 on MDN.
-")
+*/
 external exp: float => float = "exp"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns *e* (the base of natural logarithms) to the power of the given
 argument minus 1. See
 [`Math.expm1`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/expm1)
 on MDN.
-")
+*/
 external expm1: float => float = "expm1"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the largest integer less than or equal to the argument. This function
 may return values not representable by `int`, whose range is -2147483648 to
 2147483647. This is because, in JavaScript, there are only 64-bit floating
@@ -352,12 +352,12 @@ Js.Math.unsafe_floor_int(3.0) == 3
 Js.Math.unsafe_floor_int(-3.7) == -4
 Js.Math.unsafe_floor_int(1.0e15) // result is outside range of int datatype
 ```
-")
+*/
 external unsafe_floor_int: float => int = "floor"
 
 @deprecated("Please use `unsafe_floor_int` instead") let unsafe_floor = unsafe_floor_int
 
-@ocaml.doc("
+/**
 Returns the largest `int` less than or equal to the argument; the result is
 pinned to the range of the `int` data type: -2147483648 to 2147483647. See
 [`Math.floor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor)
@@ -372,7 +372,7 @@ Js.Math.floor_int(-3.1) == -4
 Js.Math.floor_int(-1.0e15) == -2147483648
 Js.Math.floor_int(1.0e15) == 2147483647
 ```
-")
+*/
 let floor_int = f =>
   if f > Js_int.toFloat(Js_int.max) {
     Js_int.max
@@ -386,7 +386,7 @@ let floor_int = f =>
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the largest integral value less than or equal to the argument. The
 result is a `float` and is not restricted to the `int` data type range. See
 [`Math.floor`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor)
@@ -400,12 +400,12 @@ Js.Math.floor_float(3.0) == 3.0
 Js.Math.floor_float(-3.1) == -4.0
 Js.Math.floor_float(2_150_000_000.3) == 2_150_000_000.0
 ```
-")
+*/
 external floor_float: float => float = "floor"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Round to nearest single precision float. See
 [`Math.fround`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/fround)
 on MDN.
@@ -416,23 +416,23 @@ on MDN.
 Js.Math.fround(5.5) == 5.5
 Js.Math.fround(5.05) == 5.050000190734863
 ```
-")
+*/
 external fround: float => float = "fround"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the square root of the sum of squares of its two arguments (the
 Pythagorean formula). See
 [`Math.hypot`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/hypot)
 on MDN.
-")
+*/
 external hypot: (float, float) => float = "hypot"
 
 @val
 @variadic
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the square root of the sum of squares of the numbers in the array
 argument (generalized Pythagorean equation). Using an array allows you to
 have more than two items. See
@@ -444,22 +444,22 @@ on MDN.
 ```rescript
 Js.Math.hypotMany([3.0, 4.0, 12.0]) == 13.0
 ```
-")
+*/
 external hypotMany: array<float> => float = "hypot"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 32-bit integer multiplication. Use this only when you need to optimize
 performance of multiplication of numbers stored as 32-bit integers. See
 [`Math.imul`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/imul)
 on MDN.
-")
+*/
 external imul: (int, int) => int = "imul"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the natural logarithm of its argument; this is the number *x* such
 that *e*<sup>*x*</sup> equals the argument. Returns `NaN` for negative
 arguments. See
@@ -472,12 +472,12 @@ on MDN.
 Js.Math.log(Js.Math._E) == 1.0
 Js.Math.log(100.0) == 4.605170185988092
 ```
-")
+*/
 external log: float => float = "log"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the natural logarithm of one plus the argument. Returns `NaN` for
 arguments less than -1. See
 [`Math.log1p`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/log1p)
@@ -489,12 +489,12 @@ on MDN.
 Js.Math.log1p(Js.Math._E -. 1.0) == 1.0
 Js.Math.log1p(99.0) == 4.605170185988092
 ```
-")
+*/
 external log1p: float => float = "log1p"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the base 10 logarithm of its argument. Returns `NaN` for negative
 arguments. See
 [`Math.log10`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/log10)
@@ -507,12 +507,12 @@ Js.Math.log10(1000.0) == 3.0
 Js.Math.log10(0.01) == -2.0
 Js.Math.log10(Js.Math.sqrt(10.0)) == 0.5
 ```
-")
+*/
 external log10: float => float = "log10"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the base 2 logarithm of its argument. Returns `NaN` for negative
 arguments. See
 [`Math.log2`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/log2)
@@ -525,89 +525,89 @@ Js.Math.log2(512.0) == 9.0
 Js.Math.log2(0.125) == -3.0
 Js.Math.log2(Js.Math._SQRT2) == 0.5000000000000001 // due to precision
 ```
-")
+*/
 external log2: float => float = "log2"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the maximum of its two integer arguments.  See
 [`Math.max`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max)
 on MDN.
-")
+*/
 external max_int: (int, int) => int = "max"
 
 @val
 @variadic
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the maximum of the integers in the given array.  See
 [`Math.max`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max)
 on MDN.
-")
+*/
 external maxMany_int: array<int> => int = "max"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the maximum of its two floating point arguments. See
 [`Math.max`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max)
 on MDN.
-")
+*/
 external max_float: (float, float) => float = "max"
 
 @val
 @variadic
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the maximum of the floating point values in the given array. See
 [`Math.max`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/max)
 on MDN.
-")
+*/
 external maxMany_float: array<float> => float = "max"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the minimum of its two integer arguments. See
 [`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min)
 on MDN.
-")
+*/
 external min_int: (int, int) => int = "min"
 
 @val
 @variadic
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the minimum of the integers in the given array. See
 [`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min)
 on MDN.
-")
+*/
 external minMany_int: array<int> => int = "min"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the minimum of its two floating point arguments. See
 [`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min)
 on MDN.
-")
+*/
 external min_float: (float, float) => float = "min"
 
 @val
 @variadic
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the minimum of the floating point values in the given array. See
 [`Math.min`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/min)
 on MDN.
-")
+*/
 external minMany_float: array<float> => float = "min"
 
 @val
 @scope("Math")
 @deprecated("use `pow_float` instead, the return type may be not int")
-@ocaml.doc("
+/**
 Raises the given base to the given exponent. (Arguments and result are
 integers.) See
 [`Math.pow`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/pow)
@@ -618,12 +618,12 @@ on MDN.
 ```rescript
 Js.Math.pow_int(~base=3, ~exp=4) == 81
 ```
-")
+*/
 external pow_int: (~base: int, ~exp: int) => int = "pow"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Raises the given base to the given exponent. (Arguments and result are
 floats.) Returns `NaN` if the result would be imaginary. See
 [`Math.pow`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/pow)
@@ -638,29 +638,29 @@ Js.Math.pow_float(~base=625.0, ~exp=0.5) == 25.0
 Js.Math.pow_float(~base=625.0, ~exp=-0.5) == 0.04
 Js.Float.isNaN(Js.Math.pow_float(~base=-2.0, ~exp=0.5)) == true
 ```
-")
+*/
 external pow_float: (~base: float, ~exp: float) => float = "pow"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns a random number in the half-closed interval [0,1). See
 [`Math.random`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random)
 on MDN.
-")
+*/
 external random: unit => float = "random"
 
-@ocaml.doc("
+/**
 A call to `random_int(minVal, maxVal)` returns a random number in the
 half-closed interval [minVal, maxVal). See
 [`Math.random`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random)
 on MDN.
-")
+*/
 let random_int = (min, max) => floor(random() *. Js_int.toFloat(max - min)) + min
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Rounds its argument to nearest integer. For numbers with a fractional portion
 of exactly 0.5, the argument is rounded to the next integer in the direction
 of positive infinity. This function may return values not representable by
@@ -677,87 +677,87 @@ Js.Math.unsafe_round(3.7) == 4
 Js.Math.unsafe_round(-3.5) == -3
 Js.Math.unsafe_round(2_150_000_000_000.3) // out of range for int
 ```
-")
+*/
 external unsafe_round: float => int = "round"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Rounds to nearest integral value (expressed as a float). See
 [`Math.round`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/round)
 on MDN.
-")
+*/
 external round: float => float = "round"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the sign of its integer argument: -1 if negative, 0 if zero, 1 if
 positive. See
 [`Math.sign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sign)
 on MDN.
-")
+*/
 external sign_int: int => int = "sign"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Returns the sign of its float argument: -1.0 if negative, 0.0 if zero, 1.0 if
 positive. See
 [`Math.sign`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sign)
 on MDN.
-")
+*/
 external sign_float: float => float = "sign"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Sine of argument, which must be specified in radians. See
 [`Math.sin`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sin)
 on MDN.
-")
+*/
 external sin: float => float = "sin"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Hyperbolic sine of argument, which must be specified in radians. See
 [`Math.sinh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sinh)
 on MDN.
-")
+*/
 external sinh: float => float = "sinh"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Square root. If the argument is negative, this function returns `NaN`. See
 [`Math.sqrt`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/sqrt)
 on MDN.
-")
+*/
 external sqrt: float => float = "sqrt"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Tangent of argument, which must be specified in radians. Returns `NaN` if the
 argument is positive infinity or negative infinity. See
 [`Math.cos`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/cos)
 on MDN.
-")
+*/
 external tan: float => float = "tan"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Hyperbolic tangent of argument, which must be specified in radians. See
 [`Math.tanh`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/tanh)
 on MDN.
-")
+*/
 external tanh: float => float = "tanh"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Truncates its argument; i.e., removes fractional digits. This function may
 return values not representable by `int`, whose range is -2147483648 to
 2147483647. This is because, in JavaScript, there are only 64-bit floating
@@ -765,14 +765,14 @@ point numbers, which can represent integers in the range ±(2<sup>53</sup>-1)
 exactly. See
 [`Math.trunc`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/trunc)
 on MDN.
-")
+*/
 external unsafe_trunc: float => int = "trunc"
 
 @val
 @scope("Math")
-@ocaml.doc("
+/**
 Truncates its argument; i.e., removes fractional digits. See
 [`Math.trunc`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/trunc)
 on MDN.
-")
+*/
 external trunc: float => float = "trunc"
diff --git a/jscomp/others/js_string.res b/jscomp/others/js_string.res
index 811d1b2b00..938c962d55 100644
--- a/jscomp/others/js_string.res
+++ b/jscomp/others/js_string.res
@@ -705,7 +705,7 @@ Js.String.splitAtMost("/", ~limit=9, "ant/bee/cat/dog/elk") == ["ant", "bee", "c
 external splitAtMost: (t, ~limit: int) => array<t> = "split"
 
 @bs.send.pipe(: t)
-@ocaml.doc("
+/**
 `splitByRe(regex, str)` splits the given `str` at every occurrence of `regex`
 and returns an array of the resulting substrings.
 
@@ -715,18 +715,18 @@ on MDN.
 ## Examples
 
 ```rescript
-Js.String.splitByRe(%re(\"/\s*[,;]\s*/\"), \"art; bed , cog ;dad\") == [
-    Some(\"art\"),
-    Some(\"bed\"),
-    Some(\"cog\"),
-    Some(\"dad\"),
+Js.String.splitByRe(%re("/\s*[,;]\s*TODO/"), "art; bed , cog ;dad") == [
+    Some("art"),
+    Some("bed"),
+    Some("cog"),
+    Some("dad"),
   ]
 ```
-")
+*/
 external splitByRe: Js_re.t => array<option<t>> = "split"
 
 @bs.send.pipe(: t)
-@ocaml.doc("
+/**
 `splitByReAtMost(regex, ~limit:n, str)` splits the given `str` at every
 occurrence of `regex` and returns an array of the first `n` resulting
 substrings. If `n` is negative or greater than the number of substrings, the
@@ -738,22 +738,22 @@ on MDN.
 ## Examples
 
 ```rescript
-Js.String.splitByReAtMost(%re(\"/\s*:\s*/\"), ~limit=3, \"one: two: three: four\") == [
-    Some(\"one\"),
-    Some(\"two\"),
-    Some(\"three\"),
+Js.String.splitByReAtMost(%re("/\s*[,;]\s*TODO/"), ~limit=3, "one: two: three: four") == [
+    Some("one"),
+    Some("two"),
+    Some("three"),
   ]
 
-Js.String.splitByReAtMost(%re(\"/\s*:\s*/\"), ~limit=0, \"one: two: three: four\") == []
+Js.String.splitByReAtMost(%re("/\s*[,;]\s*TODO/"), ~limit=0, "one: two: three: four") == []
 
-Js.String.splitByReAtMost(%re(\"/\s*:\s*/\"), ~limit=8, \"one: two: three: four\") == [
-    Some(\"one\"),
-    Some(\"two\"),
-    Some(\"three\"),
-    Some(\"four\"),
+Js.String.splitByReAtMost(%re("/\s*[,;]\s*TODO/"), ~limit=8, "one: two: three: four") == [
+    Some("one"),
+    Some("two"),
+    Some("three"),
+    Some("four"),
   ]
 ```
-")
+*/
 external splitByReAtMost: (Js_re.t, ~limit: int) => array<option<t>> = "split"
 
 @bs.send.pipe(: t)
diff --git a/jscomp/runtime/caml_format.res b/jscomp/runtime/caml_format.res
index 3dc37757f7..6fbee88afa 100644
--- a/jscomp/runtime/caml_format.res
+++ b/jscomp/runtime/caml_format.res
@@ -713,12 +713,12 @@ let float_of_string: (string, exn) => float = %raw(`function(s,exn){
 }
 `)
 
-@ocaml.doc("
+/**
    Pervasives.float_of_string : string -> float = \"?float_of_string\"
    Semantics is slightly different from javascript :
    console.assert(float_of_string('infinity')===Infinity)
    console.assert(float_of_string('Infinity')===Infinity
    parseFloat('Infinity') === Infinity
    parseFloat('infinity') === Nan
-")
+*/
 let float_of_string = (s: string): float => float_of_string(s, Failure("float_of_string"))
diff --git a/jscomp/runtime/js.res b/jscomp/runtime/js.res
index a784a7aae6..9be46892af 100644
--- a/jscomp/runtime/js.res
+++ b/jscomp/runtime/js.res
@@ -23,30 +23,62 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
 
 @@config({flags: ["-unboxed-types", "-w", "-49"]})
-@@ocaml.text(/* DESIGN:
+
+/* DESIGN:
    - It does not have any code, all its code will be inlined so that
        there will never be
    {[ require('js')]}
    - Its interface should be minimal
 */
 
-" This library provides bindings and necessary support for JS FFI.
-    It contains all bindings into [Js] namespace.
+/***
+The Js module mostly contains ReScript bindings to _standard JavaScript APIs_
+like [console.log](https://developer.mozilla.org/en-US/docs/Web/API/Console/log),
+or the JavaScript
+[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String),
+[Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), and
+[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
+classes.
+
+It is meant as a zero-abstraction interop layer and directly exposes JavaScript functions as they are. If you can find your API in this module, prefer this over an equivalent Belt helper. For example, prefer [Js.Array2](js/array2) over [Belt.Array](belt/array)
+
+## Argument Order
+
+For historical reasons, some APIs in the Js namespace (e.g. [Js.String](js/string)) are
+using the data-last argument order whereas others (e.g. [Js.Date](js/date)) are using data-first.
+
+For more information about these argument orders and the trade-offs between them, see
+[this blog post](https://www.javierchavarri.com/data-first-and-data-last-a-comparison/).
+
+_Eventually, all modules in the Js namespace are going to be migrated to data-first though._
+
+In the meantime, there are several options for dealing with the data-last APIs:
 
-    @example {[
-      [| 1;2;3;4|]
-      |. Js.Array2.map (fun x -> x + 1 )
-      |. Js.Array2.reduce (+) 0
-      |. Js.log
-    ]}
-")
+## Examples
 
-@@ocaml.text("/*")
+```rescript
+/* Js.String (data-last API used with pipe last operator) */
+Js.log("2019-11-10" |> Js.String.split("-"))
+Js.log("ReScript" |> Js.String.startsWith("Re"))
 
-@ocaml.doc(" Types for JS objects ")
+/* Js.String (data-last API used with pipe first operator) */
+Js.log("2019-11-10"->Js.String.split("-", _))
+Js.log("ReScript"->Js.String.startsWith("Re", _))
+
+/* Js.String (data-last API used without any piping) */
+Js.log(Js.String.split("-", "2019-11-10"))
+Js.log(Js.String.startsWith("Re", "ReScript"))
+```
+## Js.Xxx2 Modules
+
+Prefer `Js.Array2` over `Js.Array`, `Js.String2` over `Js.String`, etc. The latters are old modules.
+ */
+
+/** JS object type */
 type t<'a> = {..} as 'a
 
 module MapperRt = Js_mapperRt
+
 module Internal = {
   external opaqueFullApply: 'a => 'a = "%uncurried_apply"
 
@@ -55,190 +87,199 @@ module Internal = {
   external opaque: 'a => 'a = "%opaque"
 }
 
-@@ocaml.text("/*")
-
-@ocaml.doc(" nullable, value of this type can be either [null] or ['a]
-    this type is the same as type [t] in {!Null}
-")
+/**
+  Nullable value of this type can be either null or 'a. This type is equivalent to Js.Null.t.
+*/
 @unboxed
 type null<+'a> = Value('a) | @as(null) Null
 
-@ocaml.doc(" value of this type can be either [undefined] or ['a]
-    this type is the same as type [t] in {!Undefined}  ")
+/**
+  A value of this type can be either undefined or 'a. This type is equivalent to Js.Undefined.t.
+*/
 type undefined<+'a>
 
-@ocaml.doc(" value of this type can be [undefined], [null] or ['a]
-    this type is the same as type [t] n {!Null_undefined} ")
-@unboxed
-type nullable<+'a> = Value('a) | @as(null) Null | @as(undefined) Undefined
+@unboxed type nullable<+'a> = Value('a) | @as(null) Null | @as(undefined) Undefined
+
+/***
+  A value of this type can be undefined, null or 'a. This type is equivalent to Js.Null_undefined.t.
+*/
 
 type null_undefined<+'a> = nullable<'a>
 
 external toOption: nullable<'a> => option<'a> = "#nullable_to_opt"
 external undefinedToOption: undefined<'a> => option<'a> = "#undefined_to_opt"
 external nullToOption: null<'a> => option<'a> = "#null_to_opt"
-
 external isNullable: nullable<'a> => bool = "#is_nullable"
-
 external import: 'a => promise<'a> = "#import"
 
-@ocaml.doc(" The same as {!test} except that it is more permissive on the types of input ")
+/** The same as {!test} except that it is more permissive on the types of input */
 external testAny: 'a => bool = "#is_nullable"
 
-@ocaml.doc(" The promise type, defined here for interoperation across packages
-    @deprecated please use {!Js.Promise}
-")
+/**
+  The promise type, defined here for interoperation across packages.
+*/
 type promise<+'a, +'e>
 
-@ocaml.doc(" The same as [empty] in {!Js.Null} will be compiled as [null]")
+/**
+  The same as empty in `Js.Null`. Compiles to `null`.
+*/
 external null: null<'a> = "#null"
 
-@ocaml.doc(" The same as  [empty] {!Js.Undefined} will be compiled as [undefined]")
+/**
+  The same as empty `Js.Undefined`. Compiles to `undefined`.
+*/
 external undefined: undefined<'a> = "#undefined"
 
-@ocaml.doc(" [typeof x] will be compiled as [typeof x] in JS
-    Please consider functions in {!Types} for a type safe way of reflection
-")
+/**
+`typeof x` will be compiled as `typeof x` in JS. Please consider functions in
+`Js.Types` for a type safe way of reflection.
+*/
 external typeof: 'a => string = "#typeof"
 
-@val @scope("console") @ocaml.doc(" A convenience function to log everything ")
+@val @scope("console") /** Equivalent to console.log any value. */
 external log: 'a => unit = "log"
 
 @val @scope("console") external log2: ('a, 'b) => unit = "log"
 @val @scope("console") external log3: ('a, 'b, 'c) => unit = "log"
+
 @val @scope("console") external log4: ('a, 'b, 'c, 'd) => unit = "log"
 
-@val @scope("console") @variadic @ocaml.doc(" A convenience function to log more than 4 arguments ")
+@val @scope("console") @variadic /** A convenience function to console.log more than 4 arguments */
 external logMany: array<'a> => unit = "log"
 
 external eqNull: ('a, null<'a>) => bool = "%bs_equal_null"
 external eqUndefined: ('a, undefined<'a>) => bool = "%bs_equal_undefined"
 external eqNullable: ('a, nullable<'a>) => bool = "%bs_equal_nullable"
 
-@@ocaml.text(" {4 operators }")
+/* ## Operators */
 
-@ocaml.doc(" [unsafe_lt a b] will be compiled as [a < b].
+/**
+   `unsafe_lt(a, b)` will be compiled as `a < b`.
     It is marked as unsafe, since it is impossible
     to give a proper semantics for comparision which applies to any type
-")
+*/
 external unsafe_lt: ('a, 'a) => bool = "#unsafe_lt"
 
-@ocaml.doc("  [unsafe_le a b] will be compiled as [a <= b].
-     See also {!unsafe_lt}
-")
+/**
+   `unsafe_le(a, b)` will be compiled as `a <= b`.
+   See also `Js.unsafe_lt`.
+*/
 external unsafe_le: ('a, 'a) => bool = "#unsafe_le"
 
-@ocaml.doc("  [unsafe_gt a b] will be compiled as [a > b].
-     See also {!unsafe_lt}
-")
+/**
+   `unsafe_gt(a, b)` will be compiled as `a > b`.
+    See also `Js.unsafe_lt`.
+*/
 external unsafe_gt: ('a, 'a) => bool = "#unsafe_gt"
 
-@ocaml.doc("  [unsafe_ge a b] will be compiled as [a >= b].
-     See also {!unsafe_lt}
-")
+/**
+   `unsafe_ge(a, b)` will be compiled as `a >= b`.
+   See also `Js.unsafe_lt`.
+*/
 external unsafe_ge: ('a, 'a) => bool = "#unsafe_ge"
 
-@@ocaml.text(" {12 nested modules}")
+/* ## Nested Modules */
 
-@ocaml.doc(" Provide utilities around ['a null] ")
+/** Provide utilities for `Js.null<'a>` */
 module Null = Js_null
 
-@ocaml.doc(" Provide utilities around {!undefined} ")
+/** Provide utilities for `Js.undefined<'a>` */
 module Undefined = Js_undefined
 
-@ocaml.doc(" Provide utilities around {!null_undefined} ")
+/** Provide utilities for `Js.null_undefined` */
 module Nullable = Js_null_undefined
 
-@ocaml.doc(" @deprecated please use {!Js.Nullable} ")
 module Null_undefined = Js_null_undefined
 
-@ocaml.doc(" Provide utilities for dealing with Js exceptions ")
+/** Provide utilities for dealing with Js exceptions */
 module Exn = Js_exn
 
-@ocaml.doc(" Provide bindings to Js array")
+/** Provide bindings to JS array*/
 module Array = Js_array
 
-@ocaml.doc(" Provide bindings to Js array")
+/** Provide bindings to JS array*/
 module Array2 = Js_array2
 
-@ocaml.doc(" Provide bindings to JS string ")
+/** Provide bindings to JS string */
 module String = Js_string
 
-@ocaml.doc(" Provide bindings to JS string ")
+/** Provide bindings to JS string */
 module String2 = Js_string2
 
-@ocaml.doc(" Provide bindings to Js regex expression ")
+/** Provide bindings to JS regex expression */
 module Re = Js_re
 
-@ocaml.doc(" Provide bindings to JS promise ")
+/** Provide bindings to JS Promise */
 module Promise = Js_promise
 
-@ocaml.doc(" Provide bindings to JS promise ")
+/** Provide bindings to JS Promise */
 module Promise2 = Js_promise2
 
-@ocaml.doc(" Provide bindings for JS Date ")
+/** Provide bindings for JS Date */
 module Date = Js_date
 
-@ocaml.doc(" Provide utilities for JS dictionary object ")
+/** Provide utilities for JS dictionary object */
 module Dict = Js_dict
 
-@ocaml.doc(" Provide bindings to JS global functions in global namespace")
+/** Provide bindings to JS global functions in global namespace*/
 module Global = Js_global
 
-@ocaml.doc(" Provide utilities for json ")
+/** Provide utilities for json */
 module Json = Js_json
 
-@ocaml.doc(" Provide bindings for JS [Math] object ")
+/** Provide bindings for JS `Math` object */
 module Math = Js_math
 
-@ocaml.doc(" Provide utilities for {!Js.t} ")
+/** Provide utilities for `Js.t` */
 module Obj = Js_obj
 
-@ocaml.doc(" Provide bindings for JS typed array ")
+/** Provide bindings for JS typed array */
 module Typed_array = Js_typed_array
 
-@ocaml.doc(" Provide bindings for JS typed array ")
+/** Provide bindings for JS typed array */
 module TypedArray2 = Js_typed_array2
 
-@ocaml.doc(" Provide utilities for manipulating JS types  ")
+/** Provide utilities for manipulating JS types  */
 module Types = Js_types
 
-@ocaml.doc(" Provide utilities for JS float ")
+/** Provide utilities for JS float */
 module Float = Js_float
 
-@ocaml.doc(" Provide utilities for int ")
+/** Provide utilities for int */
 module Int = Js_int
 
-@ocaml.doc(" Provide utilities for bigint ")
+/** Provide utilities for bigint */
 module BigInt = Js_bigint
 
-@ocaml.doc(" Provide utilities for File ")
+/** Provide utilities for File */
 module File = Js_file
 
-@ocaml.doc(" Provide utilities for Blob ")
+/** Provide utilities for Blob */
 module Blob = Js_blob
 
-@ocaml.doc(" Provide utilities for option ")
+/** Provide utilities for option */
 module Option = Js_option
 
-@ocaml.doc(" Define the interface for result ")
+/** Define the interface for result */
 module Result = Js_result
 
-@ocaml.doc(" Provide utilities for list ")
+/** Provide utilities for list */
 module List = Js_list
 
+/** Provides bindings for JS Vector */
 module Vector = Js_vector
 
+/** Provides bindings for console */
 module Console = Js_console
 
-@ocaml.doc(" Provides bindings for ES6 Set ")
+/** Provides bindings for ES6 Set */
 module Set = Js_set
 
-@ocaml.doc(" Provides bindings for ES6 WeakSet ")
+/** Provides bindings for ES6 WeakSet */
 module WeakSet = Js_weakset
 
-@ocaml.doc(" Provides bindings for ES6 Map ")
+/** Provides bindings for ES6 Map */
 module Map = Js_map
 
-@ocaml.doc(" Provides bindings for ES6 WeakMap ")
+/** Provides bindings for ES6 WeakMap */
 module WeakMap = Js_weakmap