chore(debounce): update type annotations to use LuaCATS (#2848)

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 fun(...) Function to throttle
---@param fn (function) Function to throttle
+---@param ms number Timeout in ms
---@param timeout (number) Timeout in ms
+---@return fun(...) wrapped_fn Throttled function
---@returns (function, timer) throttled function and timer. Remember to call
+---@return uv_timer_t timer Remember to call `timer.close()` at the end or you will leak memory!
----`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
+--- Throttles a function on the trailing edge. Automatically `schedule_wrap()`s.
---- `schedule_wrap()`s.
+---@param fn fun(...) Function to throttle
----
+---@param ms number Timeout in ms
---@param fn (function) Function to throttle
+---@param last? boolean Whether to use the arguments of the last call to `fn` within the timeframe.
---@param timeout (number) Timeout in ms
+--- Default: Use arguments of the first call.
---@param last (boolean, optional) Whether to use the arguments of the last
+---@return fun(...) wrapped_fn Throttled function
----call to `fn` within the timeframe. Default: Use arguments of the first call.
+---@return uv_timer_t timer Remember to call `timer.close()` at the end or you will leak memory!
---@returns (function, timer) Throttled function and 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 fun(...) Function to debounce
---@param fn (function) Function to debounce
+---@param ms number Timeout in ms
---@param timeout (number) Timeout in ms
+---@return fun(...) wrapped_fn Debounced function
---@returns (function, timer) Debounced function and timer. Remember to call
+---@return uv_timer_t timer Remember to call `timer.close()` at the end or you will leak memory!
----`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
+--- Debounces a function on the trailing edge. Automatically `schedule_wrap()`s.
---- `schedule_wrap()`s.
+---@param fn fun(...) Function to debounce
----
+---@param ms number Timeout in ms
---@param fn (function) Function to debounce
+---@param first? boolean Whether to use the arguments of the first call to `fn` within the timeframe.
---@param timeout (number) Timeout in ms
+--- Default: Use arguments of the last call.
---@param first (boolean, optional) Whether to use the arguments of the first
+---@return fun(...) wrapped_fn Debounced function
----call to `fn` within the timeframe. Default: Use arguments of the last call.
+---@return uv_timer_t timer Remember to call `timer.close()` at the end or you will leak memory!
---@returns (function, timer) Debounced function and 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 bouncer (string) Bouncer function to test
+---@param ms? number Timeout in ms, default 2000.
---@param ms (number, optional) Timeout in ms, default 2000.
+---@param firstlast? boolean Whether to use the 'other' fn call strategy.
---@param firstlast (bool, optional) Whether to use the 'other' fn call
----strategy.
 function M.test_defer(bouncer, ms, firstlast)
   local bouncers = {
     tl = M.throttle_leading,