Object.is documentation

src/Core__Object.res

@@ -1,6 +1,37 @@
 @obj external empty: unit => {..} = ""
 
-@val external is: ('a, 'b) => bool = "Object.is"
+/**
+`is` determines if two objects are identical in all contexts. Objects, arrays, records, and other non-primitives are only identical if they reference the **exact** same object in memory. Primitives like ints, floats, and strings are identical if they have the same value. `+0` and `-0` are distinct. NaN is equal to itself. See [Object.is on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is)
+
+In most scenarios use `==` or `===` or the custom `equals` function (if provided) for the type.
+
+The `==` operator [is different in ReScript than Javascript](https://rescript-lang.org/docs/manual/latest/overview#boolean). Arrays, records and other non-primitives are equal if they have the same contents (deep equality).
+
+In ReScript, the `===` operator performs a strict equality check, like Javascript, and is similar but not identical to `is`
+
+## Examples
+
+```rescript
+Object.is(25, 13) // false
+Object.is("abc", "abc") // true
+Object.is(undefined, undefined) // true
+Object.is(undefined, null) // false
+Object.is(-0.0, 0.0) // false
+Object.is(list{1, 2}, list{1, 2}) // false
+
+Object.is([1, 2, 3], [1, 2, 3]) // false
+[1, 2, 3] == [1, 2, 3] // true
+[1, 2, 3] === [1, 2, 3] // false
+
+let fruit = {"name": "Apple" }
+Object.is(fruit, fruit) // true
+Object.is(fruit, {"name": "Apple" }) // false
+fruit == {"name": "Apple" } // true
+fruit === {"name": "Apple" } // false
+```
+*/
+@val
+external is: ('a, 'b) => bool = "Object.is"
 
 @val external create: {..} => {..} = "Object.create"
 @val external createWithProperties: ({..}, {..}) => {..} = "Object.create"