docs(collections): complete documentation (#4664)

* docs(collections): complete documentation

* work

* work

* work

* work

* fix

* fixes

* fixes

* fixes

* fixes

* tweak

_tools/check_docs.ts

@@ -20,6 +20,7 @@ import type {
 const ENTRY_POINTS = [
   "../bytes/mod.ts",
   "../datetime/mod.ts",
+  "../collections/mod.ts",
 ] as const;
 
 const MD_SNIPPET = /(?<=```ts\n)(\n|.)*(?=\n```)/g;
@@ -44,7 +45,9 @@ function assert(
 }
 
 function isFunctionDoc(document: DocNodeBase): document is DocNodeFunction {
-  return document.kind === "function";
+  return document.kind === "function" &&
+    // Ignores implementation signatures when overload signatures exist
+    (document as DocNodeFunction).functionDef.hasBody !== true;
 }
 
 function isExported(document: DocNodeBase) {

collections/aggregate_groups.ts

@@ -7,31 +7,38 @@ import { mapEntries } from "./map_entries.ts";
  * Applies the given aggregator to each group in the given grouping, returning the
  * results together with the respective group keys
  *
- * @template T input type of an item in a group in the given grouping.
- * @template A type of the accumulator value, which will match the returned record's values.
- * @example
+ * @template T Type of the values in the input record.
+ * @template A Type of the accumulator value, which will match the returned
+ * record's values.
+ *
+ * @param record The grouping to aggregate.
+ * @param aggregator The function to apply to each group.
+ *
+ * @returns A record with the same keys as the input record, but with the values
+ * being the result of applying the aggregator to each group.
+ *
+ * @example Basic usage
  * ```ts
  * import { aggregateGroups } from "@std/collections/aggregate-groups";
  * import { assertEquals } from "@std/assert/assert-equals";
  *
  * const foodProperties = {
- *   "Curry": ["spicy", "vegan"],
- *   "Omelette": ["creamy", "vegetarian"],
+ *   Curry: ["spicy", "vegan"],
+ *   Omelette: ["creamy", "vegetarian"],
  * };
+ *
  * const descriptions = aggregateGroups(
  *   foodProperties,
  *   (current, key, first, acc) => {
- *     if (first) {
- *       return `${key} is ${current}`;
- *     }
- *
- *     return `${acc} and ${current}`;
+ *     return first
+ *       ? `${key} is ${current}`
+ *       : `${acc} and ${current}`;
  *   },
  * );
  *
  * assertEquals(descriptions, {
- *   "Curry": "Curry is spicy and vegan",
- *   "Omelette": "Omelette is creamy and vegetarian",
+ *   Curry: "Curry is spicy and vegan",
+ *   Omelette: "Omelette is creamy and vegetarian",
  * });
  * ```
  */
@@ -43,7 +50,8 @@ export function aggregateGroups<T, A>(
     record,
     ([key, values]) => [
       key,
-      // Need the type assertions here because the reduce type does not support the type transition we need
+      // Need the type assertions here because the reduce type does not support
+      // the type transition we need
       values.reduce(
         (accumulator, current, currentIndex) =>
           aggregator(current, key, currentIndex === 0, accumulator),

collections/associate_by.ts

@@ -2,11 +2,21 @@
 // This module is browser compatible.
 
 /**
- * Transforms the given array into a Record, extracting the key of each element
- * using the given selector. If the selector produces the same key for multiple
- * elements, the latest one will be used (overriding the ones before it).
+ * Creates a record by associating each element of the input array with a key
+ * generated by the selector function.
  *
- * @example
+ * If the selector produces the same key for multiple elements, the latest one
+ * will be used (overriding the ones before it).
+ *
+ * @template T Type of the elements in the input array.
+ *
+ * @param array The array to transform.
+ * @param selector The function to extract the key from each element.
+ *
+ * @returns A record with the keys produced by the selector and the elements as
+ * values.
+ *
+ * @example Basic usage
  * ```ts
  * import { associateBy } from "@std/collections/associate-by";
  * import { assertEquals } from "@std/assert/assert-equals";
@@ -16,7 +26,8 @@
  *   { id: "5f8", userName: "Arnold" },
  *   { id: "d2c", userName: "Kim" },
  * ];
- * const usersById = associateBy(users, (it) => it.id);
+ *
+ * const usersById = associateBy(users, (user) => user.id);
  *
  * assertEquals(usersById, {
  *   "a2e": { id: "a2e", userName: "Anna" },

collections/associate_with.ts

@@ -2,17 +2,28 @@
 // This module is browser compatible.
 
 /**
- * Builds a new Record using the given array as keys and choosing a value for
- * each key using the given selector. If any of two pairs would have the same
- * value the latest on will be used (overriding the ones before it).
+ * Associates each element of an array with a value returned by a selector
+ * function.
  *
- * @example
+ * If any of two pairs would have the same value the latest on will be used
+ * (overriding the ones before it).
+ *
+ * @template T The type of the values returned by the selector function.
+ *
+ * @param array The array of elements to associate with values.
+ * @param selector The selector function that returns a value for each element.
+ *
+ * @returns An object where each element of the array is associated with a value
+ * returned by the selector function.
+ *
+ * @example Basic usage
  * ```ts
  * import { associateWith } from "@std/collections/associate-with";
  * import { assertEquals } from "@std/assert/assert-equals";
  *
  * const names = ["Kim", "Lara", "Jonathan"];
- * const namesToLength = associateWith(names, (it) => it.length);
+ *
+ * const namesToLength = associateWith(names, (person) => person.length);
  *
  * assertEquals(namesToLength, {
  *   "Kim": 3,

collections/chunk.ts

@@ -4,7 +4,14 @@
 /**
  * Splits the given array into chunks of the given size and returns them.
  *
- * @example
+ * @template T Type of the elements in the input array.
+ *
+ * @param array The array to split into chunks.
+ * @param size The size of the chunks. This my be a positive integer.
+ *
+ * @returns An array of chunks of the given size.
+ *
+ * @example Basic usage
  * ```ts
  * import { chunk } from "@std/collections/chunk";
  * import { assertEquals } from "@std/assert/assert-equals";