docs(array): document all

Author: unrevised6419

src/array.ts

@@ -5,14 +5,12 @@ import type { Choice, Maybe, Optional, ReadonlyArrayStrict } from './types.js';
  * Returns the first element of an array or the value itself if it's not an array.
  *
  * ```ts
- * import { firstOrSelf } from '@jagaad/utils';
- *
  * const singleValue = firstOrSelf('Hello'); // 'Hello'
  * const arrayValue = firstOrSelf(['Hello', 'World']); // 'Hello'
  * const emptyArray = firstOrSelf([]); // undefined
  * const nullValue = firstOrSelf(null); // undefined
  * const undefinedValue = firstOrSelf(undefined); // undefined
- * const numberValue = firstOrSelf(42); // 42
+ * const numberValue = firstOrSelf(0); // 0
  * const emptyString = firstOrSelf(''); // ''
  * const booleanValue = firstOrSelf(false); // false
  * ```
@@ -27,16 +25,48 @@ export function firstOrSelf<T>(value: Maybe<Arrayable<T>>): Optional<T> {
 	return value;
 }
 
+/**
+ * Inserts a separator between each element of the array.
+ *
+ * ```ts
+ * import { intersperse } from '@jagaad/utils';
+ *
+ * const result = intersperse(['a', 'b', 'c'], '-'); // ['a', '-', 'b', '-', 'c']
+ */
 export function intersperse<T>(array: ReadonlyArray<T>, separator: T): T[] {
 	return [...Array(2 * array.length - 1)].map((_, i) =>
 		i % 2 ? separator : (array[i / 2] as T),
 	);
 }
 
+/**
+ * Returns a random item from the given array.
+ *
+ * ```ts
+ * const items = ['apple', 'banana', 'cherry'];
+ * const random = randomItem(items); // Could be 'apple', 'banana', or 'cherry'
+ * ```
+ *
+ * @deprecated Use `sample` from `es-toolkit` instead.
+ */
 export function randomItem<T>(arr: ReadonlyArray<T>): T {
 	return arr[Math.floor(Math.random() * arr.length)] as T;
 }
 
+/**
+ * Returns metadata about the index of an item in a list.
+ *
+ * ```ts
+ * const list = ['apple', 'banana', 'cherry'];
+ * const meta = getIndexMeta(1, list);
+ * console.log(meta.count); // 3
+ * console.log(meta.current); // 2
+ * console.log(meta.first); // false
+ * console.log(meta.last); // false
+ * console.log(meta.odd); // true
+ * console.log(meta.even); // false
+ * ```
+ */
 export function getIndexMeta(
 	index: number,
 	list: ReadonlyArrayStrict<unknown>,
@@ -81,6 +111,18 @@ export function getIndexMeta(
 	};
 }
 
+/**
+ * Converts an array of choices into a record where the keys are the choice IDs and the values are the choice names.
+ *
+ * ```ts
+ * const choices = [
+ *   { id: '1', name: 'Choice 1' },
+ *   { id: '2', name: 'Choice 2' },
+ * ];
+ * const record = choicesToRecord(choices);
+ * console.log(record); // { '1': 'Choice 1', '2': 'Choice 2' }
+ * ```
+ */
 export function choicesToRecord(
 	choices: Maybe<ReadonlyArrayStrict<Choice>>,
 ): Record<string, string> {