From 496691f985a1aacd9a0977c558ff4ce6980e13c8 Mon Sep 17 00:00:00 2001
From: phanium <91544758+phanen@users.noreply.github.com>
Date: Tue, 17 Jun 2025 22:14:25 +0800
Subject: [PATCH] docs: vim.fs.dir.Opts type #34546

Follow the pattern of vim.fs.find.Opts
---
 runtime/doc/lua.txt    | 12 +++++++-----
 runtime/lua/vim/fs.lua | 27 +++++++++++++++++++--------
 2 files changed, 26 insertions(+), 13 deletions(-)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index a58b593ce0..45063ddc54 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2995,11 +2995,13 @@ vim.fs.dir({path}, {opts})                                      *vim.fs.dir()*
                 iterate over. The path is first normalized
                 |vim.fs.normalize()|.
       • {opts}  (`table?`) Optional keyword arguments:
-                • depth: integer|nil How deep the traverse (default 1)
-                • skip: (fun(dir_name: string): boolean)|nil Predicate to
+                • {depth}? (`integer`, default: `1`) How deep the traverse.
+                • {skip}? (`fun(dir_name: string): boolean`) Predicate to
                   control traversal. Return false to stop searching the
-                  current directory. Only useful when depth > 1
-                • follow: boolean|nil Follow symbolic links. (default: false)
+                  current directory. Only useful when depth > 1 Return an
+                  iterator over the items located in {path}
+                • {follow}? (`boolean`, default: `false`) Follow symbolic
+                  links.
 
     Return: ~
         (`Iterator`) over items in {path}. Each iteration yields two values:
@@ -3061,7 +3063,7 @@ vim.fs.find({names}, {opts})                                   *vim.fs.find()*
 
                  The function should return `true` if the given item is
                  considered a match.
-      • {opts}   (`table`) Optional keyword arguments:
+      • {opts}   (`table?`) Optional keyword arguments:
                  • {path}? (`string`) Path to begin searching from. If
                    omitted, the |current-directory| is used.
                  • {upward}? (`boolean`, default: `false`) Search upward
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 8bb4c7ca91..3d86f94c9f 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -124,6 +124,23 @@ function M.joinpath(...)
   return (path:gsub('//+', '/'))
 end
 
+--- @class vim.fs.dir.Opts
+--- @inlinedoc
+---
+--- How deep the traverse.
+--- (default: `1`)
+--- @field depth? integer
+---
+--- Predicate to control traversal.
+--- Return false to stop searching the current directory.
+--- Only useful when depth > 1
+--- Return an iterator over the items located in {path}
+--- @field skip? (fun(dir_name: string): boolean)
+---
+--- Follow symbolic links.
+--- (default: `false`)
+--- @field follow? boolean
+
 ---@alias Iterator fun(): string?, string?
 
 --- Return an iterator over the items located in {path}
@@ -131,13 +148,7 @@ end
 ---@since 10
 ---@param path (string) An absolute or relative path to the directory to iterate
 ---            over. The path is first normalized |vim.fs.normalize()|.
---- @param opts table|nil Optional keyword arguments:
----             - depth: integer|nil How deep the traverse (default 1)
----             - skip: (fun(dir_name: string): boolean)|nil Predicate
----               to control traversal. Return false to stop searching the current directory.
----               Only useful when depth > 1
----             - follow: boolean|nil Follow symbolic links. (default: false)
----
+---@param opts? vim.fs.dir.Opts Optional keyword arguments:
 ---@return Iterator over items in {path}. Each iteration yields two values: "name" and "type".
 ---        "name" is the basename of the item relative to {path}.
 ---        "type" is one of the following:
@@ -256,7 +267,7 @@ end
 ---
 ---             The function should return `true` if the given item is considered a match.
 ---
----@param opts vim.fs.find.Opts Optional keyword arguments:
+---@param opts? vim.fs.find.Opts Optional keyword arguments:
 ---@return (string[]) # Normalized paths |vim.fs.normalize()| of all matching items
 function M.find(names, opts)
   opts = opts or {}