Skip to content

Commit 04c1e1d

Browse files
fhammerschmidtfhammerschmidt
authored
Array docstrings (#7979)
1 parent 3949f60 commit 04c1e1d

File tree

2 files changed

+168
-14
lines changed

2 files changed

+168
-14
lines changed

‎packages/@rescript/runtime/Stdlib_Array.resi‎

Lines changed: 156 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,10 +24,32 @@ Map.fromArray([("foo", 1), ("bar", 2)])
2424
@val
2525
external fromIterator: Stdlib_Iterator.t<'a> => array<'a> = "Array.from"
2626

27-
// TODO: Docs
27+
/**
28+
`fromArrayLike(source)` converts an array-like value (anything with indexed items and a `length`) into a regular array.
29+
30+
See [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) on MDN.
31+
32+
## Examples
33+
34+
```rescript
35+
let source: Array.arrayLike<int> = %raw(`{0: 10, 1: 20, length: 2}`)
36+
Array.fromArrayLike(source) == [10, 20]
37+
```
38+
*/
2839
@val external fromArrayLike: arrayLike<'a> => array<'a> = "Array.from"
2940

30-
// TODO: Docs
41+
/**
42+
`fromArrayLikeWithMap(source, map)` converts an array-like value into an array and applies `map` to every element.
43+
44+
See [`Array.from`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from) on MDN.
45+
46+
## Examples
47+
48+
```rescript
49+
let source: Array.arrayLike<int> = %raw(`{0: 1, 1: 2, length: 2}`)
50+
Array.fromArrayLikeWithMap(source, x => x * 10) == [10, 20]
51+
```
52+
*/
3153
@val
3254
external fromArrayLikeWithMap: (arrayLike<'a>, 'a => 'b) => array<'b> = "Array.from"
3355

@@ -69,10 +91,42 @@ Array.fromInitializer(~length=7, i => i + 3) == [3, 4, 5, 6, 7, 8, 9]
6991
*/
7092
let fromInitializer: (~length: int, int => 'a) => array<'a>
7193

94+
/**
95+
`equal(left, right, predicate)` checks if the two arrays contain the same elements according to the equality `predicate`.
96+
97+
## Examples
98+
99+
```rescript
100+
Array.equal([1, 2, 3], [1, 2, 3], Int.equal) == true
101+
Array.equal([1, 2, 3], [1, 3, 2], Int.equal) == false
102+
```
103+
*/
72104
let equal: (array<'a>, array<'a>, ('a, 'a) => bool) => bool
73105

106+
/**
107+
`compare(left, right, comparator)` compares two arrays element by element using `comparator` and returns an `Ordering`.
108+
109+
## Examples
110+
111+
```rescript
112+
Array.compare([1, 3], [1, 2], Int.compare) == Ordering.greater
113+
Array.compare([1, 2], [1, 2], Int.compare) == Ordering.equal
114+
```
115+
*/
74116
let compare: (array<'a>, array<'a>, ('a, 'a) => Stdlib_Ordering.t) => Stdlib_Ordering.t
75117

118+
/**
119+
`isArray(value)` returns `true` when `value` is a JavaScript array and `false` otherwise.
120+
121+
See [`Array.isArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray) on MDN.
122+
123+
## Examples
124+
125+
```rescript
126+
Array.isArray([1, 2, 3]) == true
127+
Array.isArray("not an array") == false
128+
```
129+
*/
76130
@val external isArray: 'a => bool = "Array.isArray"
77131

78132
/**
@@ -368,9 +422,38 @@ array == [1, 2, 3]
368422
@send
369423
external sort: (array<'a>, ('a, 'a) => Stdlib_Ordering.t) => unit = "sort"
370424

425+
/**
426+
`splice(array, ~start, ~remove, ~insert)` removes `remove` items starting at `start` and inserts the values from `insert`.
427+
428+
Beware this will *mutate* the array.
429+
430+
See [`Array.splice`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice) on MDN.
431+
432+
## Examples
433+
434+
```rescript
435+
let items = ["a", "b", "c"]
436+
items->Array.splice(~start=1, ~remove=1, ~insert=["x"])
437+
items == ["a", "x", "c"]
438+
```
439+
*/
371440
@variadic @send
372441
external splice: (array<'a>, ~start: int, ~remove: int, ~insert: array<'a>) => unit = "splice"
373442

443+
/**
444+
`toSpliced(array, ~start, ~remove, ~insert)` returns a new array with the same edits that `splice` would perform, leaving the original unchanged.
445+
446+
See [`Array.toSpliced`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toSpliced) on MDN.
447+
448+
## Examples
449+
450+
```rescript
451+
let original = [1, 2, 3]
452+
let updated = original->Array.toSpliced(~start=1, ~remove=1, ~insert=[10])
453+
updated == [1, 10, 3]
454+
original == [1, 2, 3]
455+
```
456+
*/
374457
@variadic @send
375458
external toSpliced: (array<'a>, ~start: int, ~remove: int, ~insert: array<'a>) => array<'a> =
376459
"toSpliced"
@@ -395,6 +478,20 @@ array2 == ["Hello", "Good bye"] // Removes the item at index 1
395478
@send
396479
external removeInPlace: (array<'a>, int, @as(1) _) => unit = "splice"
397480

481+
/**
482+
`with(array, index, value)` returns a copy of `array` where the element at `index` is replaced with `value`.
483+
484+
See [`Array.with`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/with) on MDN.
485+
486+
## Examples
487+
488+
```rescript
489+
let original = ["a", "b", "c"]
490+
let replaced = original->Array.with(1, "x")
491+
replaced == ["a", "x", "c"]
492+
original == ["a", "b", "c"]
493+
```
494+
*/
398495
@send external with: (array<'a>, int, 'a) => array<'a> = "with"
399496

400497
/**
@@ -691,6 +788,17 @@ See [`Array.toString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/R
691788
@send
692789
external toString: array<'a> => string = "toString"
693790

791+
/**
792+
`toLocaleString(array)` converts each element to a locale-aware string and joins them with commas.
793+
794+
See [`Array.toLocaleString`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toLocaleString) on MDN.
795+
796+
## Examples
797+
798+
```rescript
799+
["apple", "banana"]->Array.toLocaleString == "apple,banana"
800+
```
801+
*/
694802
@send external toLocaleString: array<'a> => string = "toLocaleString"
695803

696804
/**
@@ -1125,8 +1233,54 @@ array[1] == Some("Hello")
11251233
*/
11261234
@set_index
11271235
external set: (array<'a>, int, 'a) => unit = ""
1236+
/**
1237+
`getSymbol(array, key)` retrieves the value stored under the symbol `key`, if present.
1238+
1239+
See [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) on MDN for more details about symbol keys.
1240+
1241+
## Examples
1242+
1243+
```rescript
1244+
let key = Symbol.make("meta")
1245+
let items = []
1246+
items->Array.setSymbol(key, "hello")
1247+
Array.getSymbol(items, key) == Some("hello")
1248+
```
1249+
*/
11281250
@get_index external getSymbol: (array<'a>, Stdlib_Symbol.t) => option<'b> = ""
1251+
1252+
/**
1253+
`getSymbolUnsafe(array, key)` retrieves the value stored under the symbol `key` without any safety checks.
1254+
1255+
See [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) on MDN.
1256+
1257+
## Examples
1258+
1259+
```rescript
1260+
let key = Symbol.make("meta")
1261+
let items = []
1262+
items->Array.setSymbol(key, "hello")
1263+
Array.getSymbolUnsafe(items, key) == "hello"
1264+
```
1265+
*/
11291266
@get_index external getSymbolUnsafe: (array<'a>, Stdlib_Symbol.t) => 'b = ""
1267+
1268+
/**
1269+
`setSymbol(array, key, value)` stores `value` under the symbol `key` on `array`.
1270+
1271+
Beware this will *mutate* the array.
1272+
1273+
See [`Symbol`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol) on MDN.
1274+
1275+
## Examples
1276+
1277+
```rescript
1278+
let key = Symbol.make("count")
1279+
let items = []
1280+
items->Array.setSymbol(key, 5)
1281+
Array.getSymbol(items, key) == Some(5)
1282+
```
1283+
*/
11301284
@set_index external setSymbol: (array<'a>, Stdlib_Symbol.t, 'b) => unit = ""
11311285

11321286
/**

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

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ Path Array.
5151
"kind": 12,
5252
"tags": [],
5353
"detail": "(\n array<'a>,\n ~start: int,\n ~remove: int,\n ~insert: array<'a>,\n) => unit",
54-
"documentation": null
54+
"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"}
5555
}, {
5656
"label": "concat",
5757
"kind": 12,
@@ -129,13 +129,13 @@ Path Array.
129129
"kind": 12,
130130
"tags": [],
131131
"detail": "(array<'a>, Symbol.t) => option<'b>",
132-
"documentation": null
132+
"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"}
133133
}, {
134134
"label": "getSymbolUnsafe",
135135
"kind": 12,
136136
"tags": [],
137137
"detail": "(array<'a>, Symbol.t) => 'b",
138-
"documentation": null
138+
"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"}
139139
}, {
140140
"label": "findIndexOpt",
141141
"kind": 12,
@@ -225,13 +225,13 @@ Path Array.
225225
"kind": 12,
226226
"tags": [],
227227
"detail": "array<'a> => string",
228-
"documentation": null
228+
"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"}
229229
}, {
230230
"label": "toSpliced",
231231
"kind": 12,
232232
"tags": [],
233233
"detail": "(\n array<'a>,\n ~start: int,\n ~remove: int,\n ~insert: array<'a>,\n) => array<'a>",
234-
"documentation": null
234+
"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"}
235235
}, {
236236
"label": "sort",
237237
"kind": 12,
@@ -273,7 +273,7 @@ Path Array.
273273
"kind": 12,
274274
"tags": [],
275275
"detail": "(array<'a>, int, 'a) => array<'a>",
276-
"documentation": null
276+
"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"}
277277
}, {
278278
"label": "lastIndexOfOpt",
279279
"kind": 12,
@@ -369,7 +369,7 @@ Path Array.
369369
"kind": 12,
370370
"tags": [],
371371
"detail": "(array<'a>, array<'a>, ('a, 'a) => Ordering.t) => Ordering.t",
372-
"documentation": null
372+
"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"}
373373
}, {
374374
"label": "join",
375375
"kind": 12,
@@ -393,7 +393,7 @@ Path Array.
393393
"kind": 12,
394394
"tags": [],
395395
"detail": "'a => bool",
396-
"documentation": null
396+
"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"}
397397
}, {
398398
"label": "values",
399399
"kind": 12,
@@ -429,7 +429,7 @@ Path Array.
429429
"kind": 12,
430430
"tags": [],
431431
"detail": "(arrayLike<'a>, 'a => 'b) => array<'b>",
432-
"documentation": null
432+
"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"}
433433
}, {
434434
"label": "fillAll",
435435
"kind": 12,
@@ -465,13 +465,13 @@ Path Array.
465465
"kind": 12,
466466
"tags": [],
467467
"detail": "(array<'a>, Symbol.t, 'b) => unit",
468-
"documentation": null
468+
"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"}
469469
}, {
470470
"label": "equal",
471471
"kind": 12,
472472
"tags": [],
473473
"detail": "(array<'a>, array<'a>, ('a, 'a) => bool) => bool",
474-
"documentation": null
474+
"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"}
475475
}, {
476476
"label": "joinUnsafe",
477477
"kind": 12,
@@ -609,7 +609,7 @@ Path Array.
609609
"kind": 12,
610610
"tags": [],
611611
"detail": "arrayLike<'a> => array<'a>",
612-
"documentation": null
612+
"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"}
613613
}, {
614614
"label": "indexOfFrom",
615615
"kind": 12,

0 commit comments

Comments
 (0)