fix(lua): vim.fs typing (#24608)

1 files changed, 20 insertions, 8 deletions

diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 92966523c0..7cd9e3cf04 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -20,7 +20,9 @@ local iswin = vim.uv.os_uname().sysname == 'Windows_NT'
 --- </pre>
 ---
 ---@param start (string) Initial path.
----@return function Iterator
+---@return fun(_, dir: string): string? # Iterator
+---@return nil
+---@return string|nil
 function M.parents(start)
   return function(_, dir)
     local parent = M.dirname(dir)
@@ -120,6 +122,7 @@ function M.dir(path, opts)
   return coroutine.wrap(function()
     local dirs = { { path, 1 } }
     while #dirs > 0 do
+      --- @type string, integer
       local dir0, level = unpack(table.remove(dirs, 1))
       local dir = level == 1 and dir0 or M.joinpath(path, dir0)
       local fs = vim.uv.fs_scandir(M.normalize(dir))
@@ -143,6 +146,13 @@ function M.dir(path, opts)
   end)
 end
 
+--- @class vim.fs.find.opts
+--- @field path string
+--- @field upward boolean
+--- @field stop string
+--- @field type string
+--- @field limit number
+
 --- Find files or directories (or other items as specified by `opts.type`) in the given path.
 ---
 --- Finds items given in {names} starting from {path}. If {upward} is "true"
@@ -175,7 +185,7 @@ end
 --- end, {limit = math.huge, type = 'file'})
 --- </pre>
 ---
----@param names (string|table|fun(name: string, path: string): boolean) Names of the items to find.
+---@param names (string|string[]|fun(name: string, path: string): boolean) Names of the items to find.
 ---             Must be base names, paths and globs are not supported when {names} is a string or a table.
 ---             If {names} is a function, it is called for each traversed item with args:
 ---             - name: base name of the current item
@@ -196,9 +206,9 @@ end
 ---                       - limit (number, default 1): Stop the search after
 ---                               finding this many matches. Use `math.huge` to
 ---                               place no limit on the number of matches.
----@return (table) Normalized paths |vim.fs.normalize()| of all matching items
+---@return (string[]) # Normalized paths |vim.fs.normalize()| of all matching items
 function M.find(names, opts)
-  opts = opts or {}
+  opts = opts or {} --[[@as vim.fs.find.opts]]
   vim.validate({
     names = { names, { 's', 't', 'f' } },
     path = { opts.path, 's', true },
@@ -208,13 +218,15 @@ function M.find(names, opts)
     limit = { opts.limit, 'n', true },
   })
 
-  names = type(names) == 'string' and { names } or names
+  if type(names) == 'string' then
+    names = { names }
+  end
 
   local path = opts.path or vim.uv.cwd()
   local stop = opts.stop
   local limit = opts.limit or 1
 
-  local matches = {}
+  local matches = {} --- @type string[]
 
   local function add(match)
     matches[#matches + 1] = M.normalize(match)
@@ -224,7 +236,7 @@ function M.find(names, opts)
   end
 
   if opts.upward then
-    local test
+    local test --- @type fun(p: string): string[]
 
     if type(names) == 'function' then
       test = function(p)
@@ -238,7 +250,7 @@ function M.find(names, opts)
       end
     else
       test = function(p)
-        local t = {}
+        local t = {} --- @type string[]
         for _, name in ipairs(names) do
           local f = M.joinpath(p, name)
           local stat = vim.uv.fs_stat(f)