docs(lua): clarify fs.find() documentation #24394

runtime/doc/lua.txt

@@ -2729,16 +2729,16 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts})                *vim.keymap.set()*
 Lua module: vim.fs                                                    *vim.fs*
 
 vim.fs.basename({file})                                    *vim.fs.basename()*
-    Return the basename of the given file or directory
+    Return the basename of the given path
 
     Parameters: ~
-      • {file}  (string) File or directory
+      • {file}  (string) Path
 
     Return: ~
         (string|nil) Basename of {file}
 
 vim.fs.dir({path}, {opts})                                      *vim.fs.dir()*
-    Return an iterator over the files and directories located in {path}
+    Return an iterator over the items located in {path}
 
     Parameters: ~
       • {path}  (string) An absolute or relative path to the directory to
@@ -2751,30 +2751,32 @@ vim.fs.dir({path}, {opts})                                      *vim.fs.dir()*
                   current directory. Only useful when depth > 1
 
     Return: ~
-        Iterator over files and directories in {path}. Each iteration yields
+        Iterator over items in {path}. Each iteration yields two values:
-        two values: name and type. Each "name" is the basename of the file or
+        "name" and "type". "name" is the basename of the item relative to
-        directory relative to {path}. Type is one of "file" or "directory".
+        {path}. "type" is one of the following: "file", "directory", "link",
+        "fifo", "socket", "char", "block", "unknown".
 
 vim.fs.dirname({file})                                      *vim.fs.dirname()*
-    Return the parent directory of the given file or directory
+    Return the parent directory of the given path
 
     Parameters: ~
-      • {file}  (string) File or directory
+      • {file}  (string) Path
 
     Return: ~
         (string|nil) Parent directory of {file}
 
 vim.fs.find({names}, {opts})                                   *vim.fs.find()*
-    Find files or directories in the given path.
+    Find files or directories (or other items as specified by `opts.type`) in
+    the given path.
 
-    Finds any files or directories given in {names} starting from {path}. If
+    Finds items given in {names} starting from {path}. If {upward} is "true"
-    {upward} is "true" then the search traverses upward through parent
+    then the search traverses upward through parent directories; otherwise,
-    directories; otherwise, the search traverses downward. Note that downward
+    the search traverses downward. Note that downward searches are recursive
-    searches are recursive and may search through many directories! If {stop}
+    and may search through many directories! If {stop} is non-nil, then the
-    is non-nil, then the search stops when the directory given in {stop} is
+    search stops when the directory given in {stop} is reached. The search
-    reached. The search terminates when {limit} (default 1) matches are found.
+    terminates when {limit} (default 1) matches are found. You can set {type}
-    The search can be narrowed to find only files or only directories by
+    to "file", "directory", "link", "socket", "char", "block", or "fifo" to
-    specifying {type} to be "file" or "directory", respectively.
+    narrow the search to find only that type.
 
     Examples: >lua
 
@@ -2799,14 +2801,13 @@ vim.fs.find({names}, {opts})                                   *vim.fs.find()*
 
     Parameters: ~
       • {names}  (string|table|fun(name: string, path: string): boolean) Names
-                 of the files and directories to find. Must be base names,
+                 of the items to find. Must be base names, paths and globs are
-                 paths and globs are not supported when {names} is a string or
+                 not supported when {names} is a string or a table. If {names}
-                 a table. If {names} is a function, it is called for each
+                 is a function, it is called for each traversed item with
-                 traversed file and directory with args:
+                 args:
                  • name: base name of the current item
                  • path: full path of the current item The function should
-                   return `true` if the given file or directory is considered
+                   return `true` if the given item is considered a match.
-                   a match.
       • {opts}   (table) Optional keyword arguments:
                  • path (string): Path to begin searching from. If omitted,
                    the |current-directory| is used.
@@ -2815,16 +2816,14 @@ vim.fs.find({names}, {opts})                                   *vim.fs.find()*
                    directories (recursively).
                  • stop (string): Stop searching when this directory is
                    reached. The directory itself is not searched.
-                 • type (string): Find only files ("file") or directories
+                 • type (string): Find only items of the given type. If
-                   ("directory"). If omitted, both files and directories that
+                   omitted, all items that match {names} are included.
-                   match {names} are included.
                  • 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 files or
+        (table) Normalized paths |vim.fs.normalize()| of all matching items
-        directories
 
 vim.fs.joinpath({...})                                     *vim.fs.joinpath()*
     Concatenate directories and/or file paths into a single path with
@@ -2864,7 +2863,7 @@ vim.fs.normalize({path}, {opts})                          *vim.fs.normalize()*
         (string) Normalized path
 
 vim.fs.parents({start})                                     *vim.fs.parents()*
-    Iterate over all the parents of the given file or directory.
+    Iterate over all the parents of the given path.
 
     Example: >lua
 
@@ -2882,7 +2881,7 @@ vim.fs.parents({start})                                     *vim.fs.parents()*
 <
 
     Parameters: ~
-      • {start}  (string) Initial file or directory.
+      • {start}  (string) Initial path.
 
     Return: ~
         (function) Iterator

runtime/lua/vim/fs.lua

@@ -2,7 +2,7 @@ local M = {}
 
 local iswin = vim.uv.os_uname().sysname == 'Windows_NT'
 
---- Iterate over all the parents of the given file or directory.
+--- Iterate over all the parents of the given path.
 ---
 --- Example:
 --- <pre>lua
@@ -19,7 +19,7 @@ local iswin = vim.uv.os_uname().sysname == 'Windows_NT'
 --- end
 --- </pre>
 ---
----@param start (string) Initial file or directory.
+---@param start (string) Initial path.
 ---@return function Iterator
 function M.parents(start)
   return function(_, dir)
@@ -34,9 +34,9 @@ function M.parents(start)
     start
 end
 
---- Return the parent directory of the given file or directory
+--- Return the parent directory of the given path
 ---
----@param file (string) File or directory
+---@param file (string) Path
 ---@return string|nil Parent directory of {file}
 function M.dirname(file)
   if file == nil then
@@ -57,9 +57,9 @@ function M.dirname(file)
   return (dir:gsub('\\', '/'))
 end
 
---- Return the basename of the given file or directory
+--- Return the basename of the given path
 ---
----@param file string File or directory
+---@param file string Path
 ---@return string|nil Basename of {file}
 function M.basename(file)
   if file == nil then
@@ -83,7 +83,7 @@ end
 
 ---@alias Iterator fun(): string?, string?
 
---- Return an iterator over the files and directories located in {path}
+--- Return an iterator over the items located in {path}
 ---
 ---@param path (string) An absolute or relative path to the directory to iterate
 ---            over. The path is first normalized |vim.fs.normalize()|.
@@ -93,9 +93,10 @@ end
 ---               to control traversal. Return false to stop searching the current directory.
 ---               Only useful when depth > 1
 ---
----@return Iterator over files and directories in {path}. Each iteration yields
+---@return Iterator over items in {path}. Each iteration yields two values: "name" and "type".
----        two values: name and type. Each "name" is the basename of the file or
+---        "name" is the basename of the item relative to {path}.
----        directory relative to {path}. Type is one of "file" or "directory".
+---        "type" is one of the following:
+---        "file", "directory", "link", "fifo", "socket", "char", "block", "unknown".
 function M.dir(path, opts)
   opts = opts or {}
 
@@ -142,16 +143,16 @@ function M.dir(path, opts)
   end)
 end
 
---- Find files or directories in the given path.
+--- Find files or directories (or other items as specified by `opts.type`) in the given path.
 ---
---- Finds any files or directories given in {names} starting from {path}. If
+--- Finds items given in {names} starting from {path}. If {upward} is "true"
---- {upward} is "true" then the search traverses upward through parent
+--- then the search traverses upward through parent directories; otherwise,
---- directories; otherwise, the search traverses downward. Note that downward
+--- the search traverses downward. Note that downward searches are recursive
---- searches are recursive and may search through many directories! If {stop}
+--- and may search through many directories! If {stop} is non-nil, then the
---- is non-nil, then the search stops when the directory given in {stop} is
+--- search stops when the directory given in {stop} is reached. The search
---- reached. The search terminates when {limit} (default 1) matches are found.
+--- terminates when {limit} (default 1) matches are found. You can set {type}
---- The search can be narrowed to find only files or only directories by
+--- to "file", "directory", "link", "socket", "char", "block", or "fifo"
---- specifying {type} to be "file" or "directory", respectively.
+--- to narrow the search to find only that type.
 ---
 --- Examples:
 --- <pre>lua
@@ -174,13 +175,12 @@ end
 --- end, {limit = math.huge, type = 'file'})
 --- </pre>
 ---
----@param names (string|table|fun(name: string, path: string): boolean) Names of the files
+---@param names (string|table|fun(name: string, path: string): boolean) Names of the items to find.
----             and directories 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 file and directory with args:
+---             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 file or directory is considered a match.
+---             The function should return `true` if the given item is considered a match.
 ---
 ---@param opts (table) Optional keyword arguments:
 ---                       - path (string): Path to begin searching from. If
@@ -191,14 +191,12 @@ end
 ---                                (recursively).
 ---                       - stop (string): Stop searching when this directory is
 ---                              reached. The directory itself is not searched.
----                       - type (string): Find only files ("file") or
+---                       - type (string): Find only items of the given type.
----                              directories ("directory"). If omitted, both
+---                               If omitted, all items that match {names} are included.
----                              files and directories that match {names} are
----                              included.
 ---                       - 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 files or directories
+---@return (table) Normalized paths |vim.fs.normalize()| of all matching items
 function M.find(names, opts)
   opts = opts or {}
   vim.validate({