From 7f05f40464d741ae6a834ff0ff8fdfbcab9986bc Mon Sep 17 00:00:00 2001
From: Javier Chavarri <javier.chavarri@gmail.com>
Date: Fri, 25 Aug 2023 10:07:31 +0000
Subject: [PATCH 1/2] docs: remove warnings, part 1

---
 jscomp/core/lam.mli             |  4 +-
 jscomp/melstd/array.mli         |  2 +-
 jscomp/melstd/hash_set.mli      |  4 +-
 jscomp/others/belt_Id.mli       |  4 +-
 jscomp/others/belt_Range.mli    |  4 +-
 jscomp/others/belt_Set.cppo.mli |  2 +-
 jscomp/others/sort.cppo.mli     |  8 ++--
 jscomp/runtime/js.ml            |  2 +-
 jscomp/runtime/js_internal.ml   |  2 +-
 jscomp/runtime/js_json.mli      |  1 +
 jscomp/runtime/js_promise.ml    |  3 --
 jscomp/runtime/js_re.ml         |  8 +---
 jscomp/runtime/js_string.ml     |  2 -
 jscomp/runtime/js_undefined.mli |  2 +-
 jscomp/stdlib/stdlib.cppo.mli   | 74 ++++++++++++++++-----------------
 15 files changed, 57 insertions(+), 65 deletions(-)

diff --git a/jscomp/core/lam.mli b/jscomp/core/lam.mli
index ab39e1039b..e8c87464ab 100644
--- a/jscomp/core/lam.mli
+++ b/jscomp/core/lam.mli
@@ -135,10 +135,10 @@ val false_ : t
 val unit : t
 
 val sequor : t -> t -> t
-(** convert [l || r] to [if l then true else r]*)
+(** convert [l || r] to [if l then true else r] *)
 
 val sequand : t -> t -> t
-(** convert [l && r] to [if l then r else false *)
+(** convert [l && r] to [if l then r else false] *)
 
 val not_ : Location.t -> t -> t
 (** constant folding *)
diff --git a/jscomp/melstd/array.mli b/jscomp/melstd/array.mli
index 99f9a63f82..d10e8ee0bd 100644
--- a/jscomp/melstd/array.mli
+++ b/jscomp/melstd/array.mli
@@ -27,7 +27,7 @@ include module type of struct
 end
 
 val reverse_range : 'a array -> int -> int -> unit
-(** Some utilities for {!Array} operations *)
+(** Some utilities for array operations *)
 
 val reverse_of_list : 'a list -> 'a array
 val to_list_f : 'a array -> ('a -> 'b) -> 'b list
diff --git a/jscomp/melstd/hash_set.mli b/jscomp/melstd/hash_set.mli
index bd82543375..86dd7d806d 100644
--- a/jscomp/melstd/hash_set.mli
+++ b/jscomp/melstd/hash_set.mli
@@ -22,8 +22,8 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *)
 
-(** Ideas are based on {!Hash}, 
-    however, {!Hash.add} does not really optimize and has a bad semantics for {!Hash_set}, 
+(** Ideas are based on [Hash], 
+    however, [Hash.add] does not really optimize and has a bad semantics for [Hash_set], 
     This module fixes the semantics of [add].
     [remove] is not optimized since it is not used too much 
 *)
diff --git a/jscomp/others/belt_Id.mli b/jscomp/others/belt_Id.mli
index 063797d97f..fcb8daa967 100644
--- a/jscomp/others/belt_Id.mli
+++ b/jscomp/others/belt_Id.mli
@@ -66,7 +66,7 @@ type ('key, 'id) comparable =
     Unlike normal functions, when created, it comes with a unique identity (guaranteed
     by the type system).
 
-    It can be created using function {!comparableU} or{!comparable}.
+    It can be created using function {!comparableU} or{!val-comparable}.
 
     The idea of a unique identity when created is that it makes sure two sets would type
     mismatch if they use different comparison function
@@ -117,7 +117,7 @@ type ('key, 'id) hashable =
     Unlike normal functions, when created, it comes with a unique identity (guaranteed
     by the type system).
 
-    It can be created using function {!hashableU} or {!hashable}.
+    It can be created using function {!hashableU} or {!val-hashable}.
 
     The idea of a unique identity when created is that it makes sure two hash sets would type
     mismatch if they use different comparison function
diff --git a/jscomp/others/belt_Range.mli b/jscomp/others/belt_Range.mli
index 678a8a693a..5165651c2d 100644
--- a/jscomp/others/belt_Range.mli
+++ b/jscomp/others/belt_Range.mli
@@ -47,7 +47,7 @@ val everyByU : int -> int -> step:int -> ((int -> bool)[@u]) -> bool
 val everyBy : int -> int -> step:int -> (int -> bool) -> bool
 (** [everyBy start finish ~step p]
 
-    {b See} {!Belt_Array.rangeBy}
+    {b See} {!Belt.Array.rangeBy}
 
     equivalent to [Belt.Array.(every (rangeBy start finish ~step) p)]
 *)
@@ -65,7 +65,7 @@ val someByU : int -> int -> step:int -> ((int -> bool)[@u]) -> bool
 val someBy : int -> int -> step:int -> (int -> bool) -> bool
 (** [someBy start finish ~step  p]
 
-    {b See} {!Belt_Array.rangeBy}
+    {b See} {!Belt.Array.rangeBy}
 
     equivalent to [Belt.Array.(some (rangeBy start finish ~step) p)]
 *)
diff --git a/jscomp/others/belt_Set.cppo.mli b/jscomp/others/belt_Set.cppo.mli
index 9330c66a94..d07cd6cdc9 100644
--- a/jscomp/others/belt_Set.cppo.mli
+++ b/jscomp/others/belt_Set.cppo.mli
@@ -23,7 +23,7 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *)
 
 (** This module is {!Belt.Set} specialized with value type to be a primitive type.
-    It is more efficient in general, the  API is the same with {!Belt_Set} except its value type is fixed,
+    It is more efficient in general, the  API is the same with {!Belt.Set} except its value type is fixed,
     and identity is not needed(using the built-in one)
 
     {b See} {!Belt.Set}
diff --git a/jscomp/others/sort.cppo.mli b/jscomp/others/sort.cppo.mli
index 26e4280704..712ae325bd 100644
--- a/jscomp/others/sort.cppo.mli
+++ b/jscomp/others/sort.cppo.mli
@@ -24,7 +24,7 @@
  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *)
 
 
-(** This is a specialized module for {!Belt_SortArray}, the docs in that module also
+(** This is a specialized module for {!Belt.SortArray}, the docs in that module also
     applies here, except the comparator is fixed and inlined
 *)
 
@@ -38,7 +38,7 @@ type element = string
 
 val strictlySortedLength: element array -> int
 (**
-  The same as {!Belt_SortArray.strictlySortedLength } except the comparator is fixed
+  The same as {!Belt.SortArray.strictlySortedLength } except the comparator is fixed
   @return [+n] means increasing order  [-n] means negative order
 *)
 
@@ -48,11 +48,11 @@ val isSorted: element array  -> bool
 
 val stableSortInPlace: element array -> unit
 (**
-   The same as {!Belt_SortArray.stableSortInPlaceBy} except the comparator is fixed
+   The same as {!Belt.SortArray.stableSortInPlaceBy} except the comparator is fixed
 *)
 
 val stableSort: element array -> element array
-(** The same as {!Belt_SortArray.stableSortBy} except the comparator is fixed *)
+(** The same as {!Belt.SortArray.stableSortBy} except the comparator is fixed *)
 
 val binarySearch: element array -> element -> int
 (**
diff --git a/jscomp/runtime/js.ml b/jscomp/runtime/js.ml
index f5adf514da..73a0633e23 100644
--- a/jscomp/runtime/js.ml
+++ b/jscomp/runtime/js.ml
@@ -73,7 +73,7 @@ module Null = Js_null
 (** Provide utilities around ['a null] *)
 
 module Undefined = Js_undefined
-(** Provide utilities around {!undefined} *)
+(** Provide utilities around {!type-undefined} *)
 
 module Nullable = Js_nullable
 (** Provide utilities around {!null_undefined} *)
diff --git a/jscomp/runtime/js_internal.ml b/jscomp/runtime/js_internal.ml
index dfa05e1d85..d000871b8a 100644
--- a/jscomp/runtime/js_internal.ml
+++ b/jscomp/runtime/js_internal.ml
@@ -88,7 +88,7 @@ external nullToOption : 'a null -> 'a option = "#null_to_opt"
 external isNullable : 'a nullable -> bool = "#is_nullable"
 
 external testAny : 'a -> bool = "#is_nullable"
-(** The same as {!test} except that it is more permissive on the types of input *)
+(** The same as {!isNullable} except that it is more permissive on the types of input *)
 
 external null : 'a null = "#null"
 (** The same as [empty] in {!Js.Null} will be compiled as [null]*)
diff --git a/jscomp/runtime/js_json.mli b/jscomp/runtime/js_json.mli
index 222faf5c3c..adbb4dd5eb 100644
--- a/jscomp/runtime/js_json.mli
+++ b/jscomp/runtime/js_json.mli
@@ -174,6 +174,7 @@ let getIds s =
   (* prints `1, 2, 3` *)
   let _ =
     Js.log (getIds {| { "ids" : [1, 2, 3] } |})
+]}
 
 @see <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse> MDN
 *)
diff --git a/jscomp/runtime/js_promise.ml b/jscomp/runtime/js_promise.ml
index 715ebd32bb..2c0805c64f 100644
--- a/jscomp/runtime/js_promise.ml
+++ b/jscomp/runtime/js_promise.ml
@@ -24,9 +24,6 @@
 
 (** Specialized bindings to Promise. Note: For simplicity,
     this binding does not track the error type, it treat it as an opaque type
-    {[
-
-    ]}
 *)
 
 type +'a t
diff --git a/jscomp/runtime/js_re.ml b/jscomp/runtime/js_re.ml
index e095e367fe..89402df852 100644
--- a/jscomp/runtime/js_re.ml
+++ b/jscomp/runtime/js_re.ml
@@ -36,13 +36,9 @@ and subsequent uses will ocntinue the search from the previous {! lastIndex}.
 let maybeMatches = "banana" |> Js.String.match_ [\[%re "/na+/g"\]]
 ]}
 
-@see
-  <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp>
-  JavaScript API reference on MDN
+@see <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp> JavaScript API reference on MDN
 
-@see
-  <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions>
-  JavaScript Regular Expressions Guide on MDN
+@see <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions> JavaScript Regular Expressions Guide on MDN
 *)
 
 type t
diff --git a/jscomp/runtime/js_string.ml b/jscomp/runtime/js_string.ml
index a7f0b4efb3..ea184e273c 100644
--- a/jscomp/runtime/js_string.ml
+++ b/jscomp/runtime/js_string.ml
@@ -68,7 +68,6 @@ external fromCodePoint : int -> t = "String.fromCodePoint"
   fromCodePoint 0xd55c = {js|한|js};;
   fromCodePoint 0x1f63a = {js|😺|js};;
 ]}
-
 *)
 
 external fromCodePointMany : int array -> t = "String.fromCodePoint"
@@ -87,7 +86,6 @@ external length : t -> int = "length"
 {[
   length "abcd" = 4;;
 ]}
-
 *)
 
 external get : t -> int -> t = ""
diff --git a/jscomp/runtime/js_undefined.mli b/jscomp/runtime/js_undefined.mli
index 3331a1f2af..fea662e44e 100644
--- a/jscomp/runtime/js_undefined.mli
+++ b/jscomp/runtime/js_undefined.mli
@@ -34,8 +34,8 @@ external return : 'a -> 'a t = "%identity"
 
 val testAny : 'a -> bool
 (**
-   @since 1.6.1
    Returns [true] if the given value is [empty] ([undefined])
+   @since 1.6.1
 *)
 
 external empty : 'a t = "#undefined"
diff --git a/jscomp/stdlib/stdlib.cppo.mli b/jscomp/stdlib/stdlib.cppo.mli
index 739a605eca..235985ea6e 100644
--- a/jscomp/stdlib/stdlib.cppo.mli
+++ b/jscomp/stdlib/stdlib.cppo.mli
@@ -125,26 +125,26 @@ external ( = ) : 'a -> 'a -> bool = "%equal"
    even if the two mutable objects are not the same physical object.
    Equality between functional values raises [Invalid_argument].
    Equality between cyclic data structures may not terminate.
-   Left-associative operator, see {!Ocaml_operators} for more information. *)
+   Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information. *)
 
 external ( <> ) : 'a -> 'a -> bool = "%notequal"
 (** Negation of {!Stdlib.( = )}.
-    Left-associative operator, see {!Ocaml_operators} for more information.
+    Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( < ) : 'a -> 'a -> bool = "%lessthan"
 (** See {!Stdlib.( >= )}.
-    Left-associative operator, see {!Ocaml_operators} for more information.
+    Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( > ) : 'a -> 'a -> bool = "%greaterthan"
 (** See {!Stdlib.( >= )}.
-    Left-associative operator,  see {!Ocaml_operators} for more information.
+    Left-associative operator,  see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( <= ) : 'a -> 'a -> bool = "%lessequal"
 (** See {!Stdlib.( >= )}.
-    Left-associative operator,  see {!Ocaml_operators} for more information.
+    Left-associative operator,  see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( >= ) : 'a -> 'a -> bool = "%greaterequal"
@@ -156,7 +156,7 @@ external ( >= ) : 'a -> 'a -> bool = "%greaterequal"
    of [( = )], mutable structures are compared by contents.
    Comparison between functional values raises [Invalid_argument].
    Comparison between cyclic structures may not terminate.
-   Left-associative operator, see {!Ocaml_operators} for more information.
+   Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external compare : 'a -> 'a -> int = "%compare"
@@ -202,12 +202,12 @@ external ( == ) : 'a -> 'a -> bool = "%eq"
    On non-mutable types, the behavior of [( == )] is
    implementation-dependent; however, it is guaranteed that
    [e1 == e2] implies [compare e1 e2 = 0].
-   Left-associative operator,  see {!Ocaml_operators} for more information.
+   Left-associative operator,  see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( != ) : 'a -> 'a -> bool = "%noteq"
 (** Negation of {!Stdlib.( == )}.
-    Left-associative operator,  see {!Ocaml_operators} for more information.
+    Left-associative operator,  see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 
@@ -220,14 +220,14 @@ external ( && ) : bool -> bool -> bool = "%sequand"
 (** The boolean 'and'. Evaluation is sequential, left-to-right:
    in [e1 && e2], [e1] is evaluated first, and if it returns [false],
    [e2] is not evaluated at all.
-   Right-associative operator,  see {!Ocaml_operators} for more information.
+   Right-associative operator,  see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( || ) : bool -> bool -> bool = "%sequor"
 (** The boolean 'or'. Evaluation is sequential, left-to-right:
    in [e1 || e2], [e1] is evaluated first, and if it returns [true],
    [e2] is not evaluated at all.
-   Right-associative operator,  see {!Ocaml_operators} for more information.
+   Right-associative operator,  see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 (** {1 Debugging} *)
@@ -302,14 +302,14 @@ external __POS_OF__ : 'a -> (string * int * int * int) * 'a = "%loc_POS"
 external ( |> ) : 'a -> ('a -> 'b) -> 'b = "%revapply"
 (** Reverse-application operator: [x |> f |> g] is exactly equivalent
  to [g (f (x))].
- Left-associative operator, see {!Ocaml_operators} for more information.
+ Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
  @since 4.01
 *)
 
 external ( @@ ) : ('a -> 'b) -> 'a -> 'b = "%apply"
 (** Application operator: [g @@ f @@ x] is exactly equivalent to
  [g (f (x))].
- Right-associative operator, see {!Ocaml_operators} for more information.
+ Right-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
  @since 4.01
 *)
 
@@ -321,13 +321,13 @@ external ( @@ ) : ('a -> 'b) -> 'a -> 'b = "%apply"
 
 external ( ~- ) : int -> int = "%negint"
 (** Unary negation. You can also write [- e] instead of [~- e].
-    Unary operator, see {!Ocaml_operators} for more information.
+    Unary operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 
 external ( ~+ ) : int -> int = "%identity"
 (** Unary addition. You can also write [+ e] instead of [~+ e].
-    Unary operator, see {!Ocaml_operators} for more information.
+    Unary operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
     @since 3.12
 *)
 
@@ -339,17 +339,17 @@ external pred : int -> int = "%predint"
 
 external ( + ) : int -> int -> int = "%addint"
 (** Integer addition.
-    Left-associative operator, see {!Ocaml_operators} for more information.
+    Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( - ) : int -> int -> int = "%subint"
 (** Integer subtraction.
-    Left-associative operator, , see {!Ocaml_operators} for more information.
+    Left-associative operator, , see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( * ) : int -> int -> int = "%mulint"
 (** Integer multiplication.
-    Left-associative operator, see {!Ocaml_operators} for more information.
+    Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( / ) : int -> int -> int = "%divint"
@@ -358,7 +358,7 @@ external ( / ) : int -> int -> int = "%divint"
    More precisely, if [x >= 0] and [y > 0], [x / y] is the greatest integer
    less than or equal to the real quotient of [x] by [y].  Moreover,
    [(- x) / y = x / (- y) = - (x / y)].
-   Left-associative operator, see {!Ocaml_operators} for more information.
+   Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 
    @raise Division_by_zero if the second argument is 0.
 *)
@@ -370,7 +370,7 @@ external ( mod ) : int -> int -> int = "%modint"
    [abs(x mod y) <= abs(y) - 1].
    If [y = 0], [x mod y] raises [Division_by_zero].
    Note that [x mod y] is negative only if [x < 0].
-   Left-associative operator, see {!Ocaml_operators} for more information.
+   Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 
    @raise Division_by_zero if [y] is zero.
 *)
@@ -390,17 +390,17 @@ val min_int : int
 
 external ( land ) : int -> int -> int = "%andint"
 (** Bitwise logical and.
-    Left-associative operator, see {!Ocaml_operators} for more information.
+    Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( lor ) : int -> int -> int = "%orint"
 (** Bitwise logical or.
-    Left-associative operator, see {!Ocaml_operators} for more information.
+    Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( lxor ) : int -> int -> int = "%xorint"
 (** Bitwise logical exclusive or.
-    Left-associative operator, see {!Ocaml_operators} for more information.
+    Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 val lnot : int -> int
@@ -409,7 +409,7 @@ val lnot : int -> int
 external ( lsl ) : int -> int -> int = "%lslint"
 (** [n lsl m] shifts [n] to the left by [m] bits.
     The result is unspecified if [m < 0] or [m > Sys.int_size].
-    Right-associative operator, see {!Ocaml_operators} for more information.
+    Right-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( lsr ) : int -> int -> int = "%lsrint"
@@ -417,14 +417,14 @@ external ( lsr ) : int -> int -> int = "%lsrint"
     This is a logical shift: zeroes are inserted regardless of
     the sign of [n].
     The result is unspecified if [m < 0] or [m > Sys.int_size].
-    Right-associative operator, see {!Ocaml_operators} for more information.
+    Right-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( asr ) : int -> int -> int = "%asrint"
 (** [n asr m] shifts [n] to the right by [m] bits.
     This is an arithmetic shift: the sign bit of [n] is replicated.
     The result is unspecified if [m < 0] or [m > Sys.int_size].
-    Right-associative operator, see {!Ocaml_operators} for more information.
+    Right-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 (** {1 Floating-point arithmetic}
@@ -443,33 +443,33 @@ external ( asr ) : int -> int -> int = "%asrint"
 
 external ( ~-. ) : float -> float = "%negfloat"
 (** Unary negation. You can also write [-. e] instead of [~-. e].
-    Unary operator, see {!Ocaml_operators} for more information.
+    Unary operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( ~+. ) : float -> float = "%identity"
 (** Unary addition. You can also write [+. e] instead of [~+. e].
-    Unary operator, see {!Ocaml_operators} for more information.
+    Unary operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
     @since 3.12
 *)
 
 external ( +. ) : float -> float -> float = "%addfloat"
 (** Floating-point addition.
-    Left-associative operator, see {!Ocaml_operators} for more information.
+    Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( -. ) : float -> float -> float = "%subfloat"
 (** Floating-point subtraction.
-    Left-associative operator, see {!Ocaml_operators} for more information.
+    Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( *. ) : float -> float -> float = "%mulfloat"
 (** Floating-point multiplication.
-    Left-associative operator, see {!Ocaml_operators} for more information.
+    Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( /. ) : float -> float -> float = "%divfloat"
 (** Floating-point division.
-    Left-associative operator, see {!Ocaml_operators} for more information.
+    Left-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 #ifdef BS
@@ -582,7 +582,7 @@ external abs_float : float -> float = "abs"  [@@mel.scope "Math"]
 external ( ** ) : float -> float -> float = "caml_power_float" "pow"
   [@@unboxed] [@@noalloc]
 (** Exponentiation.
-    Right-associative operator, see {!Ocaml_operators} for more information.
+    Right-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external sqrt : float -> float = "caml_sqrt_float" "sqrt"
@@ -815,7 +815,7 @@ external (^) : string -> string -> string = "#string_append"
 val ( ^ ) : string -> string -> string
 #endif
 (** String concatenation.
-    Right-associative operator, see {!Ocaml_operators} for more information.
+    Right-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 
     @raise Invalid_argument if the result is longer then
     than {!Sys.max_string_length} bytes.
@@ -946,7 +946,7 @@ external snd : 'a * 'b -> 'b = "%field1"
 
 val ( @ ) : 'a list -> 'a list -> 'a list
 (** [l0 @ l1] appends [l1] to [l0]. Same function as {!List.append}.
-  Right-associative operator, see {!Ocaml_operators} for more information.
+  Right-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
   @since 5.1 this function is tail-recursive.
 *)
 
@@ -1362,13 +1362,13 @@ external ref : 'a -> 'a ref = "%makemutable"
 external ( ! ) : 'a ref -> 'a = "%bs_ref_field0"
 (** [!r] returns the current contents of reference [r].
    Equivalent to [fun r -> r.contents].
-   Unary operator, see {!Ocaml_operators} for more information.
+   Unary operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external ( := ) : 'a ref -> 'a -> unit = "%bs_ref_setfield0"
 (** [r := a] stores the value of [a] in reference [r].
    Equivalent to [fun r v -> r.contents <- v].
-   Right-associative operator, see {!Ocaml_operators} for more information.
+   Right-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 external incr : int ref -> unit = "%incr"
@@ -1483,7 +1483,7 @@ val ( ^^ ) :
   [f2]: in case of formatted output, it accepts arguments from [f1], then
   arguments from [f2]; in case of formatted input, it returns results from
   [f1], then results from [f2].
-  Right-associative operator, see {!Ocaml_operators} for more information.
+  Right-associative operator, see {{: https://v2.ocaml.org/api/Ocaml_operators.html }Ocaml_operators} for more information.
 *)
 
 (** {1 Program termination} *)

From ef24c4ed2bf047b80115a09b83735a066380f680 Mon Sep 17 00:00:00 2001
From: Antonio Nuno Monteiro <anmonteiro@gmail.com>
Date: Fri, 24 Nov 2023 17:55:14 -0800
Subject: [PATCH 2/2] wip

---
 jscomp/melstd/array.mli   | 2 +-
 jscomp/others/belt_Id.mli | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/jscomp/melstd/array.mli b/jscomp/melstd/array.mli
index d10e8ee0bd..99f9a63f82 100644
--- a/jscomp/melstd/array.mli
+++ b/jscomp/melstd/array.mli
@@ -27,7 +27,7 @@ include module type of struct
 end
 
 val reverse_range : 'a array -> int -> int -> unit
-(** Some utilities for array operations *)
+(** Some utilities for {!Array} operations *)
 
 val reverse_of_list : 'a list -> 'a array
 val to_list_f : 'a array -> ('a -> 'b) -> 'b list
diff --git a/jscomp/others/belt_Id.mli b/jscomp/others/belt_Id.mli
index fcb8daa967..345c7d082b 100644
--- a/jscomp/others/belt_Id.mli
+++ b/jscomp/others/belt_Id.mli
@@ -66,7 +66,7 @@ type ('key, 'id) comparable =
     Unlike normal functions, when created, it comes with a unique identity (guaranteed
     by the type system).
 
-    It can be created using function {!comparableU} or{!val-comparable}.
+    It can be created using function {!comparableU} or {!val-comparable}.
 
     The idea of a unique identity when created is that it makes sure two sets would type
     mismatch if they use different comparison function