chore(collections): complete documentation (#3896)

collections/deep_merge.ts

@@ -31,7 +31,25 @@ export function deepMerge<
   other: Partial<Readonly<T>>,
   options?: Readonly<DeepMergeOptions>,
 ): T;
-
+/**
+ * Merges the two given Records, recursively merging any nested Records with the
+ * second collection overriding the first in case of conflict
+ *
+ * For arrays, maps and sets, a merging strategy can be specified to either
+ * `replace` values, or `merge` them instead. Use `includeNonEnumerable` option
+ * to include non-enumerable properties too.
+ *
+ * @example
+ * ```ts
+ * import { deepMerge } from "https://deno.land/std@$STD_VERSION/collections/deep_merge.ts";
+ * import { assertEquals } from "https://deno.land/std@$STD_VERSION/assert/assert_equals.ts";
+ *
+ * const a = { foo: true };
+ * const b = { foo: { bar: true } };
+ *
+ * assertEquals(deepMerge(a, b), { foo: { bar: true } });
+ * ```
+ */
 export function deepMerge<
   T extends Record<PropertyKey, unknown>,
   U extends Record<PropertyKey, unknown>,
@@ -279,20 +297,20 @@ export type DeepMergeOptions = {
  */
 
 /** Force intellisense to expand the typing to hide merging typings */
-type ExpandRecursively<T> = T extends Record<PropertyKey, unknown>
+export type ExpandRecursively<T> = T extends Record<PropertyKey, unknown>
   ? T extends infer O ? { [K in keyof O]: ExpandRecursively<O[K]> } : never
   : T;
 
 /** Filter of keys matching a given type */
-type PartialByType<T, U> = {
+export type PartialByType<T, U> = {
   [K in keyof T as T[K] extends U ? K : never]: T[K];
 };
 
 /** Get set values type */
-type SetValueType<T> = T extends Set<infer V> ? V : never;
+export type SetValueType<T> = T extends Set<infer V> ? V : never;
 
 /** Merge all sets types definitions from keys present in both objects */
-type MergeAllSets<
+export type MergeAllSets<
   T,
   U,
   X = PartialByType<T, Set<unknown>>,
@@ -303,10 +321,10 @@ type MergeAllSets<
 > = Z;
 
 /** Get array values type */
-type ArrayValueType<T> = T extends Array<infer V> ? V : never;
+export type ArrayValueType<T> = T extends Array<infer V> ? V : never;
 
 /** Merge all sets types definitions from keys present in both objects */
-type MergeAllArrays<
+export type MergeAllArrays<
   T,
   U,
   X = PartialByType<T, Array<unknown>>,
@@ -319,13 +337,13 @@ type MergeAllArrays<
 > = Z;
 
 /** Get map values types */
-type MapKeyType<T> = T extends Map<infer K, unknown> ? K : never;
+export type MapKeyType<T> = T extends Map<infer K, unknown> ? K : never;
 
 /** Get map values types */
-type MapValueType<T> = T extends Map<unknown, infer V> ? V : never;
+export type MapValueType<T> = T extends Map<unknown, infer V> ? V : never;
 
 /** Merge all sets types definitions from keys present in both objects */
-type MergeAllMaps<
+export type MergeAllMaps<
   T,
   U,
   X = PartialByType<T, Map<unknown, unknown>>,
@@ -339,7 +357,7 @@ type MergeAllMaps<
 > = Z;
 
 /** Merge all records types definitions from keys present in both objects */
-type MergeAllRecords<
+export type MergeAllRecords<
   T,
   U,
   Options,
@@ -351,7 +369,7 @@ type MergeAllRecords<
 > = Z;
 
 /** Exclude map, sets and array from type */
-type OmitComplexes<T> = Omit<
+export type OmitComplexes<T> = Omit<
   T,
   keyof PartialByType<
     T,
@@ -363,22 +381,22 @@ type OmitComplexes<T> = Omit<
 >;
 
 /** Object with keys in either T or U but not in both */
-type ObjectXorKeys<
+export type ObjectXorKeys<
   T,
   U,
   X = Omit<T, keyof U> & Omit<U, keyof T>,
   Y = { [K in keyof X]: X[K] },
 > = Y;
 
 /** Merge two objects, with left precedence */
-type MergeRightOmitComplexes<
+export type MergeRightOmitComplexes<
   T,
   U,
   X = ObjectXorKeys<T, U> & OmitComplexes<{ [K in keyof U]: U[K] }>,
 > = X;
 
 /** Merge two objects */
-type Merge<
+export type Merge<
   T,
   U,
   Options,

collections/drop_last_while.ts

@@ -3,7 +3,7 @@
 
 /**
  * Returns a new array that drops all elements in the given collection until the
- * last element that does not match the given predicate
+ * last element that does not match the given predicate.
  *
  * @example
  * ```ts

collections/group_by.ts

@@ -2,8 +2,6 @@
 // This module is browser compatible.
 
 /**
- * @deprecated (will be removed in 0.211.0) Use {@linkcode Object.groupBy} instead.
- *
  * Applies the given selector to each element in the given array, returning a
  * Record containing the results as keys and all values that produced that key
  * as values.
@@ -28,6 +26,8 @@
  *   },
  * );
  * ```
+ *
+ * @deprecated (will be removed in 0.211.0) Use {@linkcode Object.groupBy} instead.
  */
 export function groupBy<T, K extends PropertyKey>(
   iterable: Iterable<T>,

collections/join_to_string.ts

@@ -1,9 +1,7 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-/**
- * Options for joinToString
- */
+/** Options for {@linkcode joinToString}. */
 export type JoinToStringOptions = {
   separator?: string;
   prefix?: string;

collections/mod.ts

@@ -1,26 +1,13 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-/** Functions for specific common tasks around collection types like `Array` and
- * `Record`. This module is heavily inspired by `kotlin`s stdlib.
+/**
+ * Pure functions for common tasks around collection types like arrays and
+ * objects. Heavily inspired by
+ * [Kotlin's `kotlin.collections`]{@linkcode https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/}
+ * package.
  *
- * - All provided functions are **pure**, which also means that they do **not
- *   mutate** your inputs, **returning a new value** instead.
- * - All functions are importable on their own by referencing their snake_case
- *   named file (e.g. `collections/sort_by.ts`)
- *
- * This module re-exports several modules, and importing this module directly
- * will likely include a lot of code that you might not use.
- *
- * Consider importing the function directly. For example to import
- * {@linkcode distinctBy} import the module using the snake cased version of the
- * module:
- *
- * ```ts
- * import { distinctBy } from "https://deno.land/std@$STD_VERSION/collections/distinct_by.ts";
- * ```
- *
- * @module
+ * @module.
  */
 
 export * from "./aggregate_groups.ts";

collections/sample.ts

@@ -4,7 +4,7 @@
 import { randomInteger } from "./_utils.ts";
 
 /**
- * Returns a random element from the given array
+ * Returns a random element from the given array.
  *
  * @example
  * ```ts

collections/sort_by.ts

@@ -1,10 +1,10 @@
 // Copyright 2018-2023 the Deno authors. All rights reserved. MIT license.
 // This module is browser compatible.
 
-/** Order */
+/** Order option for {@linkcode SortByOptions}. */
 export type Order = "asc" | "desc";
 
-/** Options for sortBy */
+/** Options for {@linkcode sortBy}. */
 export type SortByOptions = {
   order: Order;
 };

collections/union.ts

@@ -2,7 +2,7 @@
 // This module is browser compatible.
 
 /**
- * Returns all distinct elements that appear in any of the given arrays
+ * Returns all distinct elements that appear in any of the given arrays.
  *
  * @example
  * ```ts