better docs and sample code

Author: jmagaram

src/Core__Object.res

@@ -25,24 +25,22 @@
 @val external seal: 'a => 'a = "Object.seal"
 @val external preventExtensions: 'a => 'a = "Object.preventExtensions"
 /**
-`freeze` freezes an object. Freezing an object makes existing properties non-writable and prevents extensions. Once an object is frozen, new properties cannot be be added, existing properties cannot be removed, and their values cannot be changed. `freeze` returns the same object that was passed in; it does not create a frozen copy.
- 
-Any attempt to change a frozen object will fail, either silently or by throwing an exception.
+`freeze` freezes an object. Freezing an object makes existing properties non-writable and prevents extensions. Once an object is frozen, new properties cannot be be added, existing properties cannot be removed, and their values cannot be changed.
 
-Rescript usually [disallows modifying objects](https://rescript-lang.org/docs/manual/latest/object#update) regardless of whether they are frozen.
+**Note:** `freeze` returns the same object that was passed in; it does not create a frozen copy. Any attempt to change a frozen object will fail, either silently or by throwing an exception. 
 
  ## Examples
 
  ```rescript
-let point = {"x": 1, "y": 3}->Object.freeze
-let pointIsFrozen = point->Object.isFrozen // true
-let fruit = {"name": "Apple" }
-let fruitIsFrozen = fruit->Object.isFrozen // false
+let obj = {"a": 1}
+obj->Object.set("a", 2) // succeeds
+obj->Object.freeze->ignore
+obj->Object.set("a", 3) // fails
  ```
  ## Specifications
-- [Updating objects in Rescript](https://rescript-lang.org/docs/manual/latest/object#update)
 - [ECMAScript Language Specification](https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-object.freeze)
 - [Object.freeze on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze)
+- [Updating objects in Rescript](https://rescript-lang.org/docs/manual/latest/object#update)
  */
 @val
 external freeze: 'a => 'a = "Object.freeze"
@@ -60,9 +58,9 @@ let fruit = {"name": "Apple" }
 let fruitIsFrozen = fruit->Object.isFrozen // false
  ```
  ## Specifications
-- [Updating objects in Rescript](https://rescript-lang.org/docs/manual/latest/object#update)
 - [ECMAScript Language Specification](https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-object.isfrozen)
 - [Object.isFrozen on MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/isFrozen)
+- [Updating objects in Rescript](https://rescript-lang.org/docs/manual/latest/object#update)
  */
 @val
 external isFrozen: 'a => bool = "Object.isFrozen"