update docs for array access to return an option

Author: jderochervlk

pages/docs/manual/latest/array-and-list.mdx

@@ -24,28 +24,54 @@ var myArray = ["hello", "world", "how are you"];
 ReScript arrays' items must have the same type, i.e. homogeneous.
 
 ### Usage
-
-Access & update an array item like so:
+#### Access
+Accessing items in an array will return an `option` and can be done like so:
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
 ```res example
 let myArray = ["hello", "world", "how are you"]
 
-let firstItem = myArray[0] // "hello"
-
-myArray[0] = "hey" // now ["hey", "world", "how are you"]
+let firstItem = myArray[0] // Some("hello")
 
-myArray->Array.push("bye")
+let tenthItem = myArray->Array.get(10) // None
 ```
 ```js
 var myArray = ["hello", "world", "how are you"];
 
 var firstItem = myArray[0];
 
+var tenthItem = myArray[10];
+```
+
+</CodeTab>
+
+The behavior of returning an `option` is new to V11 when you have [Core](api/core) open. 
+It provides a safer way to access array items, which is especially useful when you're not sure if the index is out of bounds.
+If you would like to not use an `option`, you can use [`Array.getUnsafe`](api/core/array#value-getUnsafe).
+
+#### Update
+Items in an array can be updated by assigning a value to an index or using a function:
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+```res example
+let myArray = ["hello", "world", "how are you"]
+
+myArray[0] = "hey" // now ["hey", "world", "how are you"]
+
+myArray->Array.push("?") //  ["hey", "world", "how are you", "?"]
+
+myArray->Array.set(0, "bye") //  ["bye", "world", "how are you", "?"]
+```
+```js
+var myArray = ["hello", "world", "how are you"];
+
 myArray[0] = "hey";
 
-var pushedValue = myArray.push("bye");
+myArray.push("?");
+
+myArray[0] = "bye";
 ```
 
 </CodeTab>

pages/docs/manual/latest/migrate-to-v11.mdx

@@ -62,6 +62,12 @@ Open it so it's available in the global scope.
  }
 ```
 
+One major change to be aware of is that array access now returns an `option`.
+```res
+let firstItem = myArray[0] // Some("hello")
+```
+If you would like to not use an `option`, you can use [`Array.getUnsafe`](api/core/array#value-getUnsafe).
+
 For a detailed explanation on migration to ReScript Core, please refer to its [migration guide](https://github.com/rescript-association/rescript-core#migration). A semi-automated script is available as well.
 
 See ReScript Core API docs [here](api/core).

pages/docs/manual/latest/reserved-keywords.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reserved Keyword"
+title: "Reserved Keywords"
 description: "All reserved keywords in ReScript"
 canonical: "/docs/manual/latest/reserved-keywords"
 ---