Skip to content

Commit f8b6c0e

Browse files
zthzth
committed
start working on Array docstrings
1 parent dc85ee6 commit f8b6c0e

1 file changed

Lines changed: 209 additions & 12 deletions

File tree

‎src/Core__Array.resi‎

Lines changed: 209 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,21 @@ let make: (~length: int, 'a) => array<'a>
2929
let fromInitializer: (~length: int, int => 'a) => array<'a>
3030

3131
@val external isArray: 'a => bool = "Array.isArray"
32-
@get external length: array<'a> => int = "length"
32+
33+
/**
34+
`length(array)` returns the `int` length (number of items) of the array.
35+
36+
See [`Array.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/length) on MDN.
37+
38+
## Examples
39+
```rescript
40+
let someArray = ["hi", "hello"]
41+
42+
Console.log(someArray->Array.length) // 2
43+
```
44+
*/
45+
@get
46+
external length: array<'a> => int = "length"
3347
@send external copyAllWithin: (array<'a>, ~target: int) => array<'a> = "copyWithin"
3448
@send
3549
external copyWithinToEnd: (array<'a>, ~target: int, ~start: int) => array<'a> = "copyWithin"
@@ -38,22 +52,205 @@ external copyWithin: (array<'a>, ~target: int, ~start: int, ~end: int) => array<
3852
@send external fillAllInPlace: (array<'a>, 'a) => unit = "fill"
3953
@send external fillInPlaceToEnd: (array<'a>, 'a, ~start: int) => unit = "fill"
4054
@send external fillInPlace: (array<'a>, 'a, ~start: int, ~end: int) => unit = "fill"
41-
@send external pop: array<'a> => option<'a> = "pop"
42-
@send external push: (array<'a>, 'a) => unit = "push"
43-
@variadic @send external pushMany: (array<'a>, array<'a>) => unit = "push"
44-
@send external reverseInPlace: array<'a> => unit = "reverse"
45-
@send external shift: array<'a> => option<'a> = "shift"
55+
56+
/**
57+
`pop(array)` pops off the last item in the array, and returns it.
58+
59+
Beware this will *mutate* the array.
60+
61+
See [`Array.pop`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/pop) on MDN.
62+
63+
## Examples
64+
```rescript
65+
let someArray = ["hi", "hello"]
66+
let lastItem = someArray->Array.pop // "hello"
67+
68+
Console.log(someArray) // ["hi"]. Notice last item is gone.
69+
```
70+
*/
71+
@send
72+
external pop: array<'a> => option<'a> = "pop"
73+
74+
/**
75+
`push(array, item)` pushes a new item to the end of the array.
76+
77+
Beware this will *mutate* the array.
78+
79+
See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) on MDN.
80+
81+
## Examples
82+
```rescript
83+
let someArray = ["hi", "hello"]
84+
someArray->Array.push("yay")
85+
86+
Console.log(someArray) // ["hi", "hello", "yay"]
87+
```
88+
*/
89+
@send
90+
external push: (array<'a>, 'a) => unit = "push"
91+
92+
/**
93+
`pushMany(array, itemsArray)` pushes many new items to the end of the array.
94+
95+
Beware this will *mutate* the array.
96+
97+
See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/push) on MDN.
98+
99+
## Examples
100+
```rescript
101+
let someArray = ["hi", "hello"]
102+
someArray->Array.pushMany(["yay", "wehoo"])
103+
104+
Console.log(someArray) // ["hi", "hello", "yay", "wehoo"]
105+
```
106+
*/
107+
@variadic
108+
@send
109+
external pushMany: (array<'a>, array<'a>) => unit = "push"
110+
111+
/**
112+
`reverse(array)` reverses the order of the items in the array.
113+
114+
Beware this will *mutate* the array.
115+
116+
See [`Array.reverse`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/reverse) on MDN.
117+
118+
## Examples
119+
```rescript
120+
let someArray = ["hi", "hello"]
121+
someArray->Array.reverse
122+
123+
Console.log(someArray) // ["hello", "h1"]
124+
```
125+
*/
126+
@send
127+
external reverseInPlace: array<'a> => unit = "reverse"
128+
129+
/**
130+
`shift(array)` removes the first item in the array, and returns it.
131+
132+
Beware this will *mutate* the array.
133+
134+
See [`Array.shift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/shift) on MDN.
135+
136+
## Examples
137+
```rescript
138+
let someArray = ["hi", "hello"]
139+
let lastItem = someArray->Array.shift // "hi"
140+
141+
Console.log(someArray) // ["hello"]. Notice first item is gone.
142+
```
143+
*/
144+
@send
145+
external shift: array<'a> => option<'a> = "shift"
46146
let sort: (array<'a>, ('a, 'a) => int) => array<'a>
47147
@send external sortInPlace: (array<'a>, ('a, 'a) => int) => unit = "sort"
48148
@variadic @send
49149
external spliceInPlace: (array<'a>, ~start: int, ~remove: int, ~insert: array<'a>) => unit =
50150
"splice"
51-
@send external unshift: (array<'a>, 'a) => unit = "unshift"
52-
@variadic @send external unshiftMany: (array<'a>, array<'a>) => unit = "unshift"
53-
@send external concat: (array<'a>, array<'a>) => array<'a> = "concat"
54-
@variadic @send external concatMany: (array<'a>, array<array<'a>>) => array<'a> = "concat"
55-
@send external flat: array<array<'a>> => array<'a> = "flat"
56-
@send external includes: (array<'a>, 'a) => bool = "includes"
151+
152+
/**
153+
`unshift(array, item)` inserts a new item at the start of the array.
154+
155+
Beware this will *mutate* the array.
156+
157+
See [`Array.unshift`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift) on MDN.
158+
159+
## Examples
160+
```rescript
161+
let someArray = ["hi", "hello"]
162+
someArray->Array.unshift("yay")
163+
164+
Console.log(someArray) // ["yay", "hi", "hello"]
165+
```
166+
*/
167+
@send
168+
external unshift: (array<'a>, 'a) => unit = "unshift"
169+
170+
/**
171+
`unshiftMany(array, itemsArray)` inserts many new items to the start of the array.
172+
173+
Beware this will *mutate* the array.
174+
175+
See [`Array.push`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/unshift) on MDN.
176+
177+
## Examples
178+
```rescript
179+
let someArray = ["hi", "hello"]
180+
someArray->Array.unshiftMany(["yay", "wehoo"])
181+
182+
Console.log(someArray) // ["yay", "wehoo", "hi", "hello"]
183+
```
184+
*/
185+
@variadic
186+
@send
187+
external unshiftMany: (array<'a>, array<'a>) => unit = "unshift"
188+
189+
/**
190+
`concat(array1, array2)` concatenates two arrays, creating a new array.
191+
192+
See [`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) on MDN.
193+
194+
## Examples
195+
```rescript
196+
let array1 = ["hi", "hello"]
197+
let array2 = ["yay", "wehoo"]
198+
199+
let someArray = array1->Array.concat(array2)
200+
201+
Console.log(someArray) // ["hi", "hello", "yay", "wehoo"]
202+
```
203+
*/
204+
@send
205+
external concat: (array<'a>, array<'a>) => array<'a> = "concat"
206+
207+
/**
208+
`concatMany(array1, arrays)` concatenates array1 with several other arrays, creating a new array.
209+
210+
See [`Array.concat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/concat) on MDN.
211+
212+
## Examples
213+
```rescript
214+
let array1 = ["hi", "hello"]
215+
let array2 = ["yay"]
216+
let array3 = ["wehoo"]
217+
218+
let someArray = array1->Array.concatMany([array2, array3])
219+
220+
Console.log(someArray) // ["hi", "hello", "yay", "wehoo"]
221+
```
222+
*/
223+
@variadic
224+
@send
225+
external concatMany: (array<'a>, array<array<'a>>) => array<'a> = "concat"
226+
227+
/**
228+
`flat(arrays)` flattens the provided arrays into a single array.
229+
230+
See [`Array.flat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flat) on MDN.
231+
232+
## Examples
233+
```rescript
234+
Console.log([[1], [2], [3, 4]]->Array.flat) // [1, 2, 3, 4]
235+
```
236+
*/
237+
@send
238+
external flat: array<array<'a>> => array<'a> = "flat"
239+
240+
/**
241+
`includes(array, item)` checks whether `array` includes `item`, by doing a [strict check for equality](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Strict_equality).
242+
243+
See [`Array.includes`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes) on MDN.
244+
245+
## Examples
246+
```rescript
247+
Console.log([1, 2]->Array.includes(1)) // true
248+
Console.log([1, 2]->Array.includes(3)) // false
249+
Console.log([{"language": "ReScript"}]->Array.includes({"language": "ReScript"})) // false, because of strict equality
250+
```
251+
*/
252+
@send
253+
external includes: (array<'a>, 'a) => bool = "includes"
57254
@send external indexOf: (array<'a>, 'a) => int = "indexOf"
58255
let indexOfOpt: (array<'a>, 'a) => option<int>
59256
@send external indexOfFrom: (array<'a>, 'a, int) => int = "indexOf"

0 commit comments

Comments
 (0)