docs(lua): add clarifications for fs.find() and fs.normalize() (#21132)

Co-Authored-By: Gregory Anders <8965202+gpanders@users.noreply.github.com>
Co-Authored-By: zeertzjq <zeertzjq@outlook.com>

2 files changed, 28 insertions, 24 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index c5ede97725..4055d93f6a 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2286,11 +2286,12 @@ find({names}, {opts})                                          *vim.fs.find()*
     Parameters: ~
       • {names}  (string|table|fun(name: string): boolean) Names of the files
                  and directories to find. Must be base names, paths and globs
-                 are not supported. If a function it is called per file and
-                 dir within the traversed directories to test if they match.
+                 are not supported. The function is called per file and
+                 directory within the traversed directories to test if they
+                 match {names}.
       • {opts}   (table) Optional keyword arguments:
                  • path (string): Path to begin searching from. If omitted,
-                   the current working directory is used.
+                   the |current-directory| is used.
                  • upward (boolean, default false): If true, search upward
                    through parent directories. Otherwise, search through child
                    directories (recursively).
@@ -2298,13 +2299,14 @@ find({names}, {opts})                                          *vim.fs.find()*
                    reached. The directory itself is not searched.
                  • type (string): Find only files ("file") or directories
                    ("directory"). If omitted, both files and directories that
-                   match {name} 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) The paths of all matching files or directories
+        (table) The normalized paths |vim.fs.normalize()| of all matching
+        files or directories
 
 normalize({path})                                         *vim.fs.normalize()*
     Normalize a path to a standard format. A tilde (~) character at the
@@ -2312,16 +2314,16 @@ normalize({path})                                         *vim.fs.normalize()*
     backslash (\) characters are converted to forward slashes (/). Environment
     variables are also expanded.
 
-    Example: >
+    Examples: >
 
-     vim.fs.normalize('C:\Users\jdoe')
-     => 'C:/Users/jdoe'
+       vim.fs.normalize('C:\Users\jdoe')
+       => 'C:/Users/jdoe'
 
-     vim.fs.normalize('~/src/neovim')
-     => '/home/jdoe/src/neovim'
+       vim.fs.normalize('~/src/neovim')
+       => '/home/jdoe/src/neovim'
 
-     vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
-     => '/Users/jdoe/.config/nvim/init.vim'
+       vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
+       => '/Users/jdoe/.config/nvim/init.vim'
 <
 
     Parameters: ~
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 7bd635d8b6..c7c053852d 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -79,11 +79,12 @@ end
 ---@param names (string|table|fun(name: string): boolean) Names of the files
 ---             and directories to find.
 ---             Must be base names, paths and globs are not supported.
----             If a function it is called per file and dir within the
----             traversed directories to test if they match.
+---             The function is called per file and directory within the
+---             traversed directories to test if they match {names}.
+---
 ---@param opts (table) Optional keyword arguments:
 ---                       - path (string): Path to begin searching from. If
----                              omitted, the current working directory is used.
+---                              omitted, the |current-directory| is used.
 ---                       - upward (boolean, default false): If true, search
 ---                                upward through parent directories. Otherwise,
 ---                                search through child directories
@@ -92,12 +93,13 @@ end
 ---                              reached. The directory itself is not searched.
 ---                       - type (string): Find only files ("file") or
 ---                              directories ("directory"). If omitted, both
----                              files and directories that match {name} are
+---                              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) The paths of all matching files or directories
+---
+---@return (table) The normalized paths |vim.fs.normalize()| of all matching files or directories
 function M.find(names, opts)
   opts = opts or {}
   vim.validate({
@@ -211,16 +213,16 @@ end
 --- backslash (\\) characters are converted to forward slashes (/). Environment
 --- variables are also expanded.
 ---
---- Example:
+--- Examples:
 --- <pre>
---- vim.fs.normalize('C:\\Users\\jdoe')
---- => 'C:/Users/jdoe'
+---   vim.fs.normalize('C:\\Users\\jdoe')
+---   => 'C:/Users/jdoe'
 ---
---- vim.fs.normalize('~/src/neovim')
---- => '/home/jdoe/src/neovim'
+---   vim.fs.normalize('~/src/neovim')
+---   => '/home/jdoe/src/neovim'
 ---
---- vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
---- => '/Users/jdoe/.config/nvim/init.vim'
+---   vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
+---   => '/Users/jdoe/.config/nvim/init.vim'
 --- </pre>
 ---
 ---@param path (string) Path to normalize