From 87e92ea31b2b61d45ad044cf7b2d9b66dad2a618 Mon Sep 17 00:00:00 2001
From: James Trew <66286082+jamestrew@users.noreply.github.com>
Date: Thu, 4 Jan 2024 11:24:19 -0500
Subject: [PATCH] chore(debounce): update type annotations to use LuaCATS
 (#2848)

---
 lua/telescope/debounce.lua | 58 ++++++++++++++++----------------------
 1 file changed, 25 insertions(+), 33 deletions(-)

diff --git a/lua/telescope/debounce.lua b/lua/telescope/debounce.lua
index 6e230b5..5afbb2f 100644
--- a/lua/telescope/debounce.lua
+++ b/lua/telescope/debounce.lua
@@ -18,11 +18,10 @@ local function td_validate(fn, ms)
 end
 
 --- Throttles a function on the leading edge. Automatically `schedule_wrap()`s.
----
---@param fn (function) Function to throttle
---@param timeout (number) Timeout in ms
---@returns (function, timer) throttled function and timer. Remember to call
----`timer:close()` at the end or you will leak memory!
+---@param fn fun(...) Function to throttle
+---@param ms number Timeout in ms
+---@return fun(...) wrapped_fn Throttled function
+---@return uv_timer_t timer Remember to call `timer.close()` at the end or you will leak memory!
 function M.throttle_leading(fn, ms)
   td_validate(fn, ms)
   local timer = vim.loop.new_timer()
@@ -40,15 +39,13 @@ function M.throttle_leading(fn, ms)
   return wrapped_fn, timer
 end
 
---- Throttles a function on the trailing edge. Automatically
---- `schedule_wrap()`s.
----
---@param fn (function) Function to throttle
---@param timeout (number) Timeout in ms
---@param last (boolean, optional) Whether to use the arguments of the last
----call to `fn` within the timeframe. Default: Use arguments of the first call.
---@returns (function, timer) Throttled function and timer. Remember to call
----`timer:close()` at the end or you will leak memory!
+--- Throttles a function on the trailing edge. Automatically `schedule_wrap()`s.
+---@param fn fun(...) Function to throttle
+---@param ms number Timeout in ms
+---@param last? boolean Whether to use the arguments of the last call to `fn` within the timeframe.
+--- Default: Use arguments of the first call.
+---@return fun(...) wrapped_fn Throttled function
+---@return uv_timer_t timer Remember to call `timer.close()` at the end or you will leak memory!
 function M.throttle_trailing(fn, ms, last)
   td_validate(fn, ms)
   local timer = vim.loop.new_timer()
@@ -87,11 +84,10 @@ function M.throttle_trailing(fn, ms, last)
 end
 
 --- Debounces a function on the leading edge. Automatically `schedule_wrap()`s.
----
---@param fn (function) Function to debounce
---@param timeout (number) Timeout in ms
---@returns (function, timer) Debounced function and timer. Remember to call
----`timer:close()` at the end or you will leak memory!
+---@param fn fun(...) Function to debounce
+---@param ms number Timeout in ms
+---@return fun(...) wrapped_fn Debounced function
+---@return uv_timer_t timer Remember to call `timer.close()` at the end or you will leak memory!
 function M.debounce_leading(fn, ms)
   td_validate(fn, ms)
   local timer = vim.loop.new_timer()
@@ -110,15 +106,13 @@ function M.debounce_leading(fn, ms)
   return wrapped_fn, timer
 end
 
---- Debounces a function on the trailing edge. Automatically
---- `schedule_wrap()`s.
----
---@param fn (function) Function to debounce
---@param timeout (number) Timeout in ms
---@param first (boolean, optional) Whether to use the arguments of the first
----call to `fn` within the timeframe. Default: Use arguments of the last call.
---@returns (function, timer) Debounced function and timer. Remember to call
----`timer:close()` at the end or you will leak memory!
+--- Debounces a function on the trailing edge. Automatically `schedule_wrap()`s.
+---@param fn fun(...) Function to debounce
+---@param ms number Timeout in ms
+---@param first? boolean Whether to use the arguments of the first call to `fn` within the timeframe.
+--- Default: Use arguments of the last call.
+---@return fun(...) wrapped_fn Debounced function
+---@return uv_timer_t timer Remember to call `timer.close()` at the end or you will leak memory!
 function M.debounce_trailing(fn, ms, first)
   td_validate(fn, ms)
   local timer = vim.loop.new_timer()
@@ -148,11 +142,9 @@ function M.debounce_trailing(fn, ms, first)
 end
 
 --- Test deferment methods (`{throttle,debounce}_{leading,trailing}()`).
----
---@param bouncer (string) Bouncer function to test
---@param ms (number, optional) Timeout in ms, default 2000.
---@param firstlast (bool, optional) Whether to use the 'other' fn call
----strategy.
+---@param bouncer string Bouncer function to test
+---@param ms? number Timeout in ms, default 2000.
+---@param firstlast? boolean Whether to use the 'other' fn call strategy.
 function M.test_defer(bouncer, ms, firstlast)
   local bouncers = {
     tl = M.throttle_leading,