From 6ef0cbf59588eea26dbdbd17277a38cec315be9c Mon Sep 17 00:00:00 2001
From: Tooster <5300963+T3sT3ro@users.noreply.github.com>
Date: Tue, 16 Dec 2025 23:12:53 +0100
Subject: [PATCH] fix: clean up JSDocs causing errors during generate-docs.mts
 script

Running generate-docs.mts script reported errors due to missing JSDoc
for many function overloads. This commit cleans up those cases, adding
comments when they are missing or removing duplicate/redundant function
declarations.
---
 src/compat/array/countBy.ts     | 21 +++++++++++++++++++++
 src/compat/array/drop.ts        |  9 +++++++++
 src/compat/array/flatten.ts     |  8 ++++++++
 src/compat/array/lastIndexOf.ts |  6 ------
 src/compat/array/map.ts         |  7 +++++++
 src/compat/array/size.ts        |  6 ++++++
 src/compat/array/sortBy.ts      |  8 ++++++++
 src/compat/array/uniqBy.ts      |  8 ++++++++
 src/compat/function/debounce.ts |  9 +++++++++
 src/compat/function/identity.ts |  6 ++++++
 src/compat/function/once.ts     |  7 +++++++
 src/compat/string/split.ts      |  8 ++++++++
 src/compat/string/trim.ts       |  8 ++++++++
 src/compat/util/cond.ts         |  6 ++++++
 src/compat/util/stubArray.ts    |  5 +++++
 src/compat/util/stubFalse.ts    |  5 +++++
 src/compat/util/stubString.ts   |  5 +++++
 src/compat/util/stubTrue.ts     |  5 +++++
 src/object/omit.ts              |  1 -
 19 files changed, 131 insertions(+), 7 deletions(-)

diff --git a/src/compat/array/countBy.ts b/src/compat/array/countBy.ts
index 5996b49dc..daaff6c23 100644
--- a/src/compat/array/countBy.ts
+++ b/src/compat/array/countBy.ts
@@ -20,11 +20,32 @@ export function countBy<T>(
   iteratee?: ValueIteratee<T>
 ): Record<string, number>;
 
+/**
+ * Creates an object composed of keys generated from the results of running each element of collection through
+ * iteratee. The corresponding value of each key is the number of times the key was returned by iteratee. The
+ * iteratee is invoked with one argument: (value).
+ *
+ * @param collection The collection to iterate over.
+ * @param iteratee The function invoked per iteration.
+ * @return Returns the composed aggregate object.
+ *
+ * @example
+ * countBy({ a: 6.1, b: 4.2, c: 6.3 }, Math.floor); // => { '4': 1, '6': 2 }
+ */
 export function countBy<T extends object>(
   collection: T | null | undefined,
   iteratee?: ValueIteratee<T[keyof T]>
 ): Record<string, number>;
 
+/**
+ * Creates an object composed of keys generated from the results of running each element of collection through
+ * iteratee. The corresponding value of each key is the number of times the key was returned by iteratee. The
+ * iteratee is invoked with one argument: (value).
+ *
+ * @param {any} collection The collection to iterate over.
+ * @param {any} iteratee The function invoked per iteration.
+ * @return {Record<string, number>} Returns the composed aggregate object.
+ */
 export function countBy(collection: any, iteratee?: any): Record<string, number> {
   if (collection == null) {
     return {} as Record<string, number>;
diff --git a/src/compat/array/drop.ts b/src/compat/array/drop.ts
index f4a834d4a..4c00985ae 100644
--- a/src/compat/array/drop.ts
+++ b/src/compat/array/drop.ts
@@ -22,6 +22,15 @@ import { toInteger } from '../util/toInteger.ts';
  */
 export function drop<T>(array: ArrayLike<T> | null | undefined, n?: number): T[];
 
+/**
+ * Removes a specified number of elements from the beginning of an array and returns the rest.
+ *
+ * @template T The type of elements in the array.
+ * @param {ArrayLike<T> | null | undefined} collection The array from which to drop elements.
+ * @param {number} itemsCount The number of elements to drop from the beginning of the array.
+ * @param {unknown} guard Enables use as an iteratee for methods like `_.map`.
+ * @returns {T[]} A new array with the specified number of elements removed from the start.
+ */
 export function drop<T>(collection: ArrayLike<T> | null | undefined, itemsCount = 1, guard?: unknown): T[] {
   if (!isArrayLike(collection)) {
     return [];
diff --git a/src/compat/array/flatten.ts b/src/compat/array/flatten.ts
index 57abc41f8..55d12b9cd 100644
--- a/src/compat/array/flatten.ts
+++ b/src/compat/array/flatten.ts
@@ -14,6 +14,14 @@ import { isArrayLike } from '../predicate/isArrayLike.ts';
  */
 export function flatten<T>(value: ArrayLike<T | readonly T[]> | null | undefined): T[];
 
+/**
+ * Flattens array up to depth times.
+ *
+ * @template T
+ * @param {ArrayLike<T> | null | undefined} value The array to flatten.
+ * @param {number} depth The maximum recursion depth.
+ * @returns {T[]} Returns the new flattened array.
+ */
 export function flatten<T>(value: ArrayLike<T | readonly T[]> | null | undefined, depth = 1): T[] {
   const result: T[] = [];
   const flooredDepth = Math.floor(depth);
diff --git a/src/compat/array/lastIndexOf.ts b/src/compat/array/lastIndexOf.ts
index 6f2d83e08..555d57ceb 100644
--- a/src/compat/array/lastIndexOf.ts
+++ b/src/compat/array/lastIndexOf.ts
@@ -19,12 +19,6 @@ import { isArrayLike } from '../predicate/isArrayLike.ts';
  * lastIndexOf([1, 2, 1, 2], 2, true);
  * // => 3
  */
-export function lastIndexOf<T>(
-  array: ArrayLike<T> | null | undefined,
-  searchElement: T,
-  fromIndex?: true | number
-): number;
-
 export function lastIndexOf<T>(
   array: ArrayLike<T> | null | undefined,
   searchElement: T,
diff --git a/src/compat/array/map.ts b/src/compat/array/map.ts
index 85c6a8af4..dd88ddcca 100644
--- a/src/compat/array/map.ts
+++ b/src/compat/array/map.ts
@@ -127,6 +127,13 @@ export function map<T>(
   iteratee?: object
 ): boolean[];
 
+/**
+ * Maps each element in a collection using the provided iteratee.
+ *
+ * @param {any[] | ArrayLike<any> | Record<any, any> | null | undefined} collection The collection to iterate over.
+ * @param {((value: any, index: PropertyKey, collection: any) => any) | PropertyKey | object | null} _iteratee The iteratee invoked per element.
+ * @returns {any[]} Returns the new mapped array.
+ */
 export function map(
   collection: any[] | ArrayLike<any> | Record<any, any> | null | undefined,
   _iteratee?: ((value: any, index: PropertyKey, collection: any) => any) | PropertyKey | object | null
diff --git a/src/compat/array/size.ts b/src/compat/array/size.ts
index 3f8692043..c74617ecd 100644
--- a/src/compat/array/size.ts
+++ b/src/compat/array/size.ts
@@ -38,6 +38,12 @@ import { isNil } from '../../predicate/isNil.ts';
  */
 export function size(collection: object | string | null | undefined): number;
 
+/**
+ * Gets the size of collection by returning its length for array-like values or the number of own enumerable string keyed properties for objects.
+ *
+ * @param {any} target The collection to inspect.
+ * @returns {number} Returns the collection size.
+ */
 export function size(target: any): number {
   if (isNil(target)) {
     return 0;
diff --git a/src/compat/array/sortBy.ts b/src/compat/array/sortBy.ts
index 8ee639cf9..37c629363 100644
--- a/src/compat/array/sortBy.ts
+++ b/src/compat/array/sortBy.ts
@@ -77,6 +77,14 @@ export function sortBy<T extends object>(
   ...iteratees: Array<Many<ObjectIteratee<T>>>
 ): Array<T[keyof T]>;
 
+/**
+ * Sorts a collection based on iteratees.
+ *
+ * @template T
+ * @param {ArrayLike<T> | object | null | undefined} collection The collection to iterate over.
+ * @param {...any[]} criteria The iteratees to sort by.
+ * @returns {T[]} Returns the new sorted array.
+ */
 export function sortBy<T = any>(collection: ArrayLike<T> | object | null | undefined, ...criteria: any[]): T[] {
   const length = criteria.length;
   // Enables use as an iteratee for methods like `_.reduce` and `_.map`.
diff --git a/src/compat/array/uniqBy.ts b/src/compat/array/uniqBy.ts
index 6f0230ed4..ee0d9ba48 100644
--- a/src/compat/array/uniqBy.ts
+++ b/src/compat/array/uniqBy.ts
@@ -17,6 +17,14 @@ import { iteratee as createIteratee } from '../util/iteratee.ts';
  * // => [2.1, 1.2]
  */
 export function uniqBy<T>(array: ArrayLike<T> | null | undefined, iteratee: ValueIteratee<T>): T[];
+/**
+ * Creates a duplicate-free version of an array, using an optional transform function.
+ *
+ * @template T
+ * @param {ArrayLike<T> | null | undefined} array The array to inspect.
+ * @param {((value: T) => unknown) | PropertyKey | [keyof T, unknown] | Partial<T>} iteratee The transform function.
+ * @returns {T[]} Returns the new duplicate-free array.
+ */
 export function uniqBy<T>(
   array: ArrayLike<T> | null | undefined,
   iteratee: ((value: T) => unknown) | PropertyKey | [keyof T, unknown] | Partial<T> = identity
diff --git a/src/compat/function/debounce.ts b/src/compat/function/debounce.ts
index 559985b3b..2479d6b6e 100644
--- a/src/compat/function/debounce.ts
+++ b/src/compat/function/debounce.ts
@@ -158,6 +158,15 @@ export function debounce<T extends (...args: any) => any>(
   options?: DebounceSettings
 ): DebouncedFunc<T>;
 
+/**
+ * Creates a debounced function that delays invoking the provided function.
+ *
+ * @template F
+ * @param {F} func The function to debounce.
+ * @param {number} debounceMs The number of milliseconds to delay.
+ * @param {DebounceSettings} options The options object.
+ * @returns {DebouncedFunc<F>} Returns the new debounced function.
+ */
 export function debounce<F extends (...args: any[]) => any>(
   func: F,
   debounceMs = 0,
diff --git a/src/compat/function/identity.ts b/src/compat/function/identity.ts
index 850c5194a..156ea9209 100644
--- a/src/compat/function/identity.ts
+++ b/src/compat/function/identity.ts
@@ -40,6 +40,12 @@ export function identity<T>(value: T): T;
  */
 export function identity(): undefined;
 
+/**
+ * Returns the first argument it receives.
+ *
+ * @param {any} x The value to return.
+ * @returns {any} Returns x.
+ */
 export function identity(x?: any): any {
   return x;
 }
diff --git a/src/compat/function/once.ts b/src/compat/function/once.ts
index a280a3834..1a687ce6f 100644
--- a/src/compat/function/once.ts
+++ b/src/compat/function/once.ts
@@ -1,5 +1,12 @@
 import { once as onceToolkit } from '../../function/once.ts';
 
+/**
+ * Creates a function that is restricted to invoking func once.
+ *
+ * @template T
+ * @param {T} func The function to restrict.
+ * @returns {T} Returns the new restricted function.
+ */
 export function once<T extends (...args: any) => any>(func: T): T {
   return onceToolkit(func);
 }
diff --git a/src/compat/string/split.ts b/src/compat/string/split.ts
index e77fe925c..620b807ca 100644
--- a/src/compat/string/split.ts
+++ b/src/compat/string/split.ts
@@ -36,6 +36,14 @@ export function split(string: string | null | undefined, separator?: RegExp | st
  */
 export function split(string: string | null | undefined, index: string | number, guard: object): string[];
 
+/**
+ * Splits string by separator.
+ *
+ * @param {any} string The string to split.
+ * @param {any} separator The separator pattern to split by.
+ * @param {any} limit The length to truncate results to.
+ * @returns {string[]} Returns the string segments.
+ */
 export function split(string: any, separator?: any, limit?: any): string[] {
   return toString(string).split(separator as string, limit);
 }
diff --git a/src/compat/string/trim.ts b/src/compat/string/trim.ts
index 2b0b5d4bb..a9fa3d5b7 100644
--- a/src/compat/string/trim.ts
+++ b/src/compat/string/trim.ts
@@ -28,6 +28,14 @@ export function trim(string?: string, chars?: string): string;
  */
 export function trim(string: string, index: string | number, guard: object): string;
 
+/**
+ * Removes leading and trailing whitespace or specified characters from string.
+ *
+ * @param {any} str The string to trim.
+ * @param {any} chars The characters to trim.
+ * @param {any} guard Enables use as an iteratee for methods like map.
+ * @returns {string} Returns the trimmed string.
+ */
 export function trim(str: any, chars?: any, guard?: any): string {
   if (str == null) {
     return '';
diff --git a/src/compat/util/cond.ts b/src/compat/util/cond.ts
index 8706c465d..1a6d4e262 100644
--- a/src/compat/util/cond.ts
+++ b/src/compat/util/cond.ts
@@ -59,6 +59,12 @@ export function cond<R>(pairs: Array<[truthy: () => boolean, falsey: () => R]>):
  */
 export function cond<T, R>(pairs: Array<[truthy: (val: T) => boolean, falsey: (val: T) => R]>): (val: T) => R;
 
+/**
+ * Creates a function that iterates over pairs and invokes the corresponding function of the first predicate to return truthy.
+ *
+ * @param {any[][]} pairs The predicate-function pairs.
+ * @returns {(...args: any[]) => unknown} Returns the new composite function.
+ */
 export function cond(pairs: any[][]): (...args: any[]) => unknown {
   const length = pairs.length;
 
diff --git a/src/compat/util/stubArray.ts b/src/compat/util/stubArray.ts
index 4a333a096..3cf797e0d 100644
--- a/src/compat/util/stubArray.ts
+++ b/src/compat/util/stubArray.ts
@@ -7,6 +7,11 @@
  */
 export function stubArray(): any[];
 
+/**
+ * Returns a new empty array.
+ *
+ * @returns {any[]} A new empty array.
+ */
 export function stubArray(): any[] {
   return [];
 }
diff --git a/src/compat/util/stubFalse.ts b/src/compat/util/stubFalse.ts
index 674df0356..4810907c1 100644
--- a/src/compat/util/stubFalse.ts
+++ b/src/compat/util/stubFalse.ts
@@ -16,6 +16,11 @@ export function stubFalse(): false;
  */
 export function stubFalse(): false;
 
+/**
+ * Returns false.
+ *
+ * @returns {false} false.
+ */
 export function stubFalse(): false {
   return false;
 }
diff --git a/src/compat/util/stubString.ts b/src/compat/util/stubString.ts
index ea7d75a7a..a0da8b663 100644
--- a/src/compat/util/stubString.ts
+++ b/src/compat/util/stubString.ts
@@ -7,6 +7,11 @@
  */
 export function stubString(): string;
 
+/**
+ * Returns an empty string.
+ *
+ * @returns {string} An empty string.
+ */
 export function stubString(): string {
   return '';
 }
diff --git a/src/compat/util/stubTrue.ts b/src/compat/util/stubTrue.ts
index bfc45bf74..22a417b32 100644
--- a/src/compat/util/stubTrue.ts
+++ b/src/compat/util/stubTrue.ts
@@ -16,6 +16,11 @@ export function stubTrue(): true;
  */
 export function stubTrue(): true;
 
+/**
+ * Returns true.
+ *
+ * @returns {true} true.
+ */
 export function stubTrue(): true {
   return true;
 }
diff --git a/src/object/omit.ts b/src/object/omit.ts
index c1e7bf8db..cabc2bf14 100644
--- a/src/object/omit.ts
+++ b/src/object/omit.ts
@@ -34,7 +34,6 @@ export function omit<T extends Record<PropertyKey, any>, K extends keyof T>(obj:
  * const result = omit(obj, keysToOmit);
  * // result will be { a: 1 }
  */
-export function omit<T extends Record<PropertyKey, any>>(obj: T, keys: readonly PropertyKey[]): Partial<T>;
 export function omit<T extends Record<PropertyKey, any>>(obj: T, keys: readonly PropertyKey[]): Partial<T> {
   const result = { ...obj };