Array docstrings

packages/@rescript/runtime/Stdlib_Array.resi

@@ -24,10 +24,32 @@ Map.fromArray([("foo", 1), ("bar", 2)])
 @val
 external fromIterator: Stdlib_Iterator.t<'a> => array<'a> = "Array.from"
 
-// TODO: Docs
+/**
+`fromArrayLike(source)` converts an array-like value (anything with indexed items and a `length`) into a regular array.
+
+See [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) on MDN.
+
+## Examples
+
+```rescript
+let source: Array.arrayLike<int> = %raw(`{0: 10, 1: 20, length: 2}`)
+Array.fromArrayLike(source) == [10, 20]
+```
+*/
 @val external fromArrayLike: arrayLike<'a> => array<'a> = "Array.from"
 
-// TODO: Docs
+/**
+`fromArrayLikeWithMap(source, map)` converts an array-like value into an array and applies `map` to every element.
+
+See [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) on MDN.
+
+## Examples
+
+```rescript
+let source: Array.arrayLike<int> = %raw(`{0: 1, 1: 2, length: 2}`)
+Array.fromArrayLikeWithMap(source, x => x * 10) == [10, 20]
+```
+*/
 @val
 external fromArrayLikeWithMap: (arrayLike<'a>, 'a => 'b) => array<'b> = "Array.from"
 
@@ -69,10 +91,42 @@ Array.fromInitializer(~length=7, i => i + 3) == [3, 4, 5, 6, 7, 8, 9]
 */
 let fromInitializer: (~length: int, int => 'a) => array<'a>
 
+/**
+`equal(left, right, predicate)` checks if the two arrays contain the same elements according to the equality `predicate`.
+
+## Examples
+
+```rescript
+Array.equal([1, 2, 3], [1, 2, 3], Int.equal) == true
+Array.equal([1, 2, 3], [1, 3, 2], Int.equal) == false
+```
+*/
 let equal: (array<'a>, array<'a>, ('a, 'a) => bool) => bool
 
+/**
+`compare(left, right, comparator)` compares two arrays element by element using `comparator` and returns an `Ordering`.
+
+## Examples
+
+```rescript
+Array.compare([1, 3], [1, 2], Int.compare) == Ordering.greater
+Array.compare([1, 2], [1, 2], Int.compare) == Ordering.equal
+```
+*/
 let compare: (array<'a>, array<'a>, ('a, 'a) => Stdlib_Ordering.t) => Stdlib_Ordering.t
 
+/**
+`isArray(value)` returns `true` when `value` is a JavaScript array and `false` otherwise.
+
+See [`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray) on MDN.
+
+## Examples
+
+```rescript
+Array.isArray([1, 2, 3]) == true
+Array.isArray("not an array") == false
+```
+*/
 @val external isArray: 'a => bool = "Array.isArray"
 
 /**
@@ -368,9 +422,38 @@ array == [1, 2, 3]
 @send
 external sort: (array<'a>, ('a, 'a) => Stdlib_Ordering.t) => unit = "sort"
 
+/**
+`splice(array, ~start, ~remove, ~insert)` removes `remove` items starting at `start` and inserts the values from `insert`.
+
+Beware this will *mutate* the array.
+
+See [`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) on MDN.
+
+## Examples
+
+```rescript
+let items = ["a", "b", "c"]
+items->Array.splice(~start=1, ~remove=1, ~insert=["x"])
+items == ["a", "x", "c"]
+```
+*/
 @variadic @send
 external splice: (array<'a>, ~start: int, ~remove: int, ~insert: array<'a>) => unit = "splice"
 
+/**
+`toSpliced(array, ~start, ~remove, ~insert)` returns a new array with the same edits that `splice` would perform, leaving the original unchanged.
+
+See [`Array.toSpliced`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toSpliced) on MDN.
+
+## Examples
+
+```rescript
+let original = [1, 2, 3]
+let updated = original->Array.toSpliced(~start=1, ~remove=1, ~insert=[10])
+updated == [1, 10, 3]
+original == [1, 2, 3]
+```
+*/
 @variadic @send
 external toSpliced: (array<'a>, ~start: int, ~remove: int, ~insert: array<'a>) => array<'a> =
   "toSpliced"
@@ -395,6 +478,20 @@ array2 == ["Hello", "Good bye"] // Removes the item at index 1
 @send
 external removeInPlace: (array<'a>, int, @as(1) _) => unit = "splice"
 
+/**
+`with(array, index, value)` returns a copy of `array` where the element at `index` is replaced with `value`.
+
+See [`Array.with`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/with) on MDN.
+
+## Examples
+
+```rescript
+let original = ["a", "b", "c"]
+let replaced = original->Array.with(1, "x")
+replaced == ["a", "x", "c"]
+original == ["a", "b", "c"]
+```
+*/
 @send external with: (array<'a>, int, 'a) => array<'a> = "with"
 
 /**
@@ -691,6 +788,17 @@ See [`Array.toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/R
 @send
 external toString: array<'a> => string = "toString"
 
+/**
+`toLocaleString(array)` converts each element to a locale-aware string and joins them with commas.
+
+See [`Array.toLocaleString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toLocaleString) on MDN.
+
+## Examples
+
+```rescript
+["apple", "banana"]->Array.toLocaleString == "apple,banana"
+```
+*/
 @send external toLocaleString: array<'a> => string = "toLocaleString"
 
 /**
@@ -1125,8 +1233,54 @@ array[1] == Some("Hello")
 */
 @set_index
 external set: (array<'a>, int, 'a) => unit = ""
+/**
+`getSymbol(array, key)` retrieves the value stored under the symbol `key`, if present.
+
+See [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) on MDN for more details about symbol keys.
+
+## Examples
+
+```rescript
+let key = Symbol.make("meta")
+let items = []
+items->Array.setSymbol(key, "hello")
+Array.getSymbol(items, key) == Some("hello")
+```
+*/
 @get_index external getSymbol: (array<'a>, Stdlib_Symbol.t) => option<'b> = ""
+
+/**
+`getSymbolUnsafe(array, key)` retrieves the value stored under the symbol `key` without any safety checks.
+
+See [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) on MDN.
+
+## Examples
+
+```rescript
+let key = Symbol.make("meta")
+let items = []
+items->Array.setSymbol(key, "hello")
+Array.getSymbolUnsafe(items, key) == "hello"
+```
+*/
 @get_index external getSymbolUnsafe: (array<'a>, Stdlib_Symbol.t) => 'b = ""
+
+/**
+`setSymbol(array, key, value)` stores `value` under the symbol `key` on `array`.
+
+Beware this will *mutate* the array.
+
+See [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) on MDN.
+
+## Examples
+
+```rescript
+let key = Symbol.make("count")
+let items = []
+items->Array.setSymbol(key, 5)
+Array.getSymbol(items, key) == Some(5)
+```
+*/
 @set_index external setSymbol: (array<'a>, Stdlib_Symbol.t, 'b) => unit = ""
 
 /**

tests/analysis_tests/tests/src/expected/Completion.res.txt

@@ -51,7 +51,7 @@ Path Array.
     "kind": 12,
     "tags": [],
     "detail": "(\n  array<'a>,\n  ~start: int,\n  ~remove: int,\n  ~insert: array<'a>,\n) => unit",
-    "documentation": null
+    "documentation": {"kind": "markdown", "value": "\n`splice(array, ~start, ~remove, ~insert)` removes `remove` items starting at `start` and inserts the values from `insert`.\n\nBeware this will *mutate* the array.\n\nSee [`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) on MDN.\n\n## Examples\n\n```rescript\nlet items = [\"a\", \"b\", \"c\"]\nitems->Array.splice(~start=1, ~remove=1, ~insert=[\"x\"])\nitems == [\"a\", \"x\", \"c\"]\n```\n"}
   }, {
     "label": "concat",
     "kind": 12,
@@ -129,13 +129,13 @@ Path Array.
     "kind": 12,
     "tags": [],
     "detail": "(array<'a>, Symbol.t) => option<'b>",
-    "documentation": null
+    "documentation": {"kind": "markdown", "value": "\n`getSymbol(array, key)` retrieves the value stored under the symbol `key`, if present.\n\nSee [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) on MDN for more details about symbol keys.\n\n## Examples\n\n```rescript\nlet key = Symbol.make(\"meta\")\nlet items = []\nitems->Array.setSymbol(key, \"hello\")\nArray.getSymbol(items, key) == Some(\"hello\")\n```\n"}
   }, {
     "label": "getSymbolUnsafe",
     "kind": 12,
     "tags": [],
     "detail": "(array<'a>, Symbol.t) => 'b",
-    "documentation": null
+    "documentation": {"kind": "markdown", "value": "\n`getSymbolUnsafe(array, key)` retrieves the value stored under the symbol `key` without any safety checks.\n\nSee [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) on MDN.\n\n## Examples\n\n```rescript\nlet key = Symbol.make(\"meta\")\nlet items = []\nitems->Array.setSymbol(key, \"hello\")\nArray.getSymbolUnsafe(items, key) == \"hello\"\n```\n"}
   }, {
     "label": "findIndexOpt",
     "kind": 12,
@@ -225,13 +225,13 @@ Path Array.
     "kind": 12,
     "tags": [],
     "detail": "array<'a> => string",
-    "documentation": null
+    "documentation": {"kind": "markdown", "value": "\n`toLocaleString(array)` converts each element to a locale-aware string and joins them with commas.\n\nSee [`Array.toLocaleString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toLocaleString) on MDN.\n\n## Examples\n\n```rescript\n[\"apple\", \"banana\"]->Array.toLocaleString == \"apple,banana\"\n```\n"}
   }, {
     "label": "toSpliced",
     "kind": 12,
     "tags": [],
     "detail": "(\n  array<'a>,\n  ~start: int,\n  ~remove: int,\n  ~insert: array<'a>,\n) => array<'a>",
-    "documentation": null
+    "documentation": {"kind": "markdown", "value": "\n`toSpliced(array, ~start, ~remove, ~insert)` returns a new array with the same edits that `splice` would perform, leaving the original unchanged.\n\nSee [`Array.toSpliced`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toSpliced) on MDN.\n\n## Examples\n\n```rescript\nlet original = [1, 2, 3]\nlet updated = original->Array.toSpliced(~start=1, ~remove=1, ~insert=[10])\nupdated == [1, 10, 3]\noriginal == [1, 2, 3]\n```\n"}
   }, {
     "label": "sort",
     "kind": 12,
@@ -273,7 +273,7 @@ Path Array.
     "kind": 12,
     "tags": [],
     "detail": "(array<'a>, int, 'a) => array<'a>",
-    "documentation": null
+    "documentation": {"kind": "markdown", "value": "\n`with(array, index, value)` returns a copy of `array` where the element at `index` is replaced with `value`.\n\nSee [`Array.with`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/with) on MDN.\n\n## Examples\n\n```rescript\nlet original = [\"a\", \"b\", \"c\"]\nlet replaced = original->Array.with(1, \"x\")\nreplaced == [\"a\", \"x\", \"c\"]\noriginal == [\"a\", \"b\", \"c\"]\n```\n"}
   }, {
     "label": "lastIndexOfOpt",
     "kind": 12,
@@ -369,7 +369,7 @@ Path Array.
     "kind": 12,
     "tags": [],
     "detail": "(array<'a>, array<'a>, ('a, 'a) => Ordering.t) => Ordering.t",
-    "documentation": null
+    "documentation": {"kind": "markdown", "value": "\n`compare(left, right, comparator)` compares two arrays element by element using `comparator` and returns an `Ordering`.\n\n## Examples\n\n```rescript\nArray.compare([1, 3], [1, 2], Int.compare) == Ordering.greater\nArray.compare([1, 2], [1, 2], Int.compare) == Ordering.equal\n```\n"}
   }, {
     "label": "join",
     "kind": 12,
@@ -393,7 +393,7 @@ Path Array.
     "kind": 12,
     "tags": [],
     "detail": "'a => bool",
-    "documentation": null
+    "documentation": {"kind": "markdown", "value": "\n`isArray(value)` returns `true` when `value` is a JavaScript array and `false` otherwise.\n\nSee [`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray) on MDN.\n\n## Examples\n\n```rescript\nArray.isArray([1, 2, 3]) == true\nArray.isArray(\"not an array\") == false\n```\n"}
   }, {
     "label": "values",
     "kind": 12,
@@ -429,7 +429,7 @@ Path Array.
     "kind": 12,
     "tags": [],
     "detail": "(arrayLike<'a>, 'a => 'b) => array<'b>",
-    "documentation": null
+    "documentation": {"kind": "markdown", "value": "\n`fromArrayLikeWithMap(source, map)` converts an array-like value into an array and applies `map` to every element.\n\nSee [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) on MDN.\n\n## Examples\n\n```rescript\nlet source: Array.arrayLike<int> = %raw(`{0: 1, 1: 2, length: 2}`)\nArray.fromArrayLikeWithMap(source, x => x * 10) == [10, 20]\n```\n"}
   }, {
     "label": "fillAll",
     "kind": 12,
@@ -465,13 +465,13 @@ Path Array.
     "kind": 12,
     "tags": [],
     "detail": "(array<'a>, Symbol.t, 'b) => unit",
-    "documentation": null
+    "documentation": {"kind": "markdown", "value": "\n`setSymbol(array, key, value)` stores `value` under the symbol `key` on `array`.\n\nBeware this will *mutate* the array.\n\nSee [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) on MDN.\n\n## Examples\n\n```rescript\nlet key = Symbol.make(\"count\")\nlet items = []\nitems->Array.setSymbol(key, 5)\nArray.getSymbol(items, key) == Some(5)\n```\n"}
   }, {
     "label": "equal",
     "kind": 12,
     "tags": [],
     "detail": "(array<'a>, array<'a>, ('a, 'a) => bool) => bool",
-    "documentation": null
+    "documentation": {"kind": "markdown", "value": "\n`equal(left, right, predicate)` checks if the two arrays contain the same elements according to the equality `predicate`.\n\n## Examples\n\n```rescript\nArray.equal([1, 2, 3], [1, 2, 3], Int.equal) == true\nArray.equal([1, 2, 3], [1, 3, 2], Int.equal) == false\n```\n"}
   }, {
     "label": "joinUnsafe",
     "kind": 12,
@@ -609,7 +609,7 @@ Path Array.
     "kind": 12,
     "tags": [],
     "detail": "arrayLike<'a> => array<'a>",
-    "documentation": null
+    "documentation": {"kind": "markdown", "value": "\n`fromArrayLike(source)` converts an array-like value (anything with indexed items and a `length`) into a regular array.\n\nSee [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) on MDN.\n\n## Examples\n\n```rescript\nlet source: Array.arrayLike<int> = %raw(`{0: 10, 1: 20, length: 2}`)\nArray.fromArrayLike(source) == [10, 20]\n```\n"}
   }, {
     "label": "indexOfFrom",
     "kind": 12,