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

runtime/doc/lua.txt

@@ -2884,11 +2884,11 @@ vim.fs.find({names}, {opts})                                   *vim.fs.find()*
 <
 
     Parameters: ~
-      • {names}  (string|table|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:
+      • {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
                  • path: full path of the current item The function should
                    return `true` if the given item is considered a match.
@@ -2907,7 +2907,7 @@ vim.fs.find({names}, {opts})                                   *vim.fs.find()*
                    number of matches.
 
     Return: ~
-        (table) Normalized paths |vim.fs.normalize()| of all matching items
+        (string[]) Normalized paths |vim.fs.normalize()| of all matching items
 
 vim.fs.joinpath({...})                                     *vim.fs.joinpath()*
     Concatenate directories and/or file paths into a single path with
@@ -2967,8 +2967,10 @@ vim.fs.parents({start})                                     *vim.fs.parents()*
     Parameters: ~
       • {start}  (string) Initial path.
 
-    Return: ~
-        (function) Iterator
+    Return (multiple): ~
+        fun(_, dir: string): string? Iterator
+        nil
+        (string|nil)
 
 
 ==============================================================================

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)