From 6cdab150bc161a35ca6356a4d1b4add17c52eb4b Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Thu, 30 Jul 2026 15:09:19 -0400
Subject: docs: misc #41063

---
 runtime/lua/vim/fs.lua | 35 +++++++++++++++++------------------
 1 file changed, 17 insertions(+), 18 deletions(-)

(limited to 'runtime/lua/vim/fs.lua')

diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 57e0da4650..1c48944807 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -191,8 +191,7 @@ end
 --- (default: `false`)
 --- @field follow? boolean
 ---
---- Normalize {path} via |vim.fs.normalize()|. Set `false` to use {path} literally, e.g. to list a
---- directory whose name contains `~` or `$`.
+--- Expand "~" and "$" in {path} before scanning the directory.
 --- (default: `true`)
 --- @field normalize? boolean
 
@@ -678,10 +677,10 @@ end
 --- (default: `true` in Windows, `false` otherwise)
 --- @field win? boolean
 
---- Normalize a path to a standard format. A tilde (~) character at the beginning of the path is
---- expanded to the user's home directory and environment variables are also expanded. "." and ".."
---- components are also resolved, except when the path is relative and trying to resolve it would
---- result in an absolute path.
+--- Normalize a path to a standard format. Expands environment variables, and tilde "~" at the
+--- beginning of the path. Resolves "." and ".." components, except when the path is relative and
+--- resolving it would produce an absolute path.
+---
 --- - "." as the only part in a relative path:
 ---   - "." => "."
 ---   - "././" => "."
@@ -691,20 +690,20 @@ end
 --- - ".." in the root directory returns the root directory.
 ---   - "/../../" => "/"
 ---
---- On Windows, backslash (\) characters are converted to forward slashes (/).
+--- On Windows, backslashes (`\`) are converted to forward slashes (`/`).
 ---
 --- Examples:
---- ```
---- [[C:\Users\jdoe]]                         => "C:/Users/jdoe"
---- "~/src/neovim"                            => "/home/jdoe/src/neovim"
---- "$XDG_CONFIG_HOME/nvim/init.vim"          => "/Users/jdoe/.config/nvim/init.vim"
---- "~/src/nvim/api/../tui/./tui.c"           => "/home/jdoe/src/nvim/tui/tui.c"
---- "./foo/bar"                               => "foo/bar"
---- "foo/../../../bar"                        => "../../bar"
---- "/home/jdoe/../../../bar"                 => "/bar"
---- "C:foo/../../baz"                         => "C:../baz"
---- "C:/foo/../../baz"                        => "C:/baz"
---- [[\\?\UNC\server\share\foo\..\..\..\bar]] => "//?/UNC/server/share/bar"
+--- ```lua
+--- [[C:\Users\jdoe]]                         --> "C:/Users/jdoe"
+--- "~/src/neovim"                            --> "/home/jdoe/src/neovim"
+--- "$XDG_CONFIG_HOME/nvim/init.vim"          --> "/Users/jdoe/.config/nvim/init.vim"
+--- "~/src/nvim/api/../tui/./tui.c"           --> "/home/jdoe/src/nvim/tui/tui.c"
+--- "./foo/bar"                               --> "foo/bar"
+--- "foo/../../../bar"                        --> "../../bar"
+--- "/home/jdoe/../../../bar"                 --> "/bar"
+--- "C:foo/../../baz"                         --> "C:../baz"
+--- "C:/foo/../../baz"                        --> "C:/baz"
+--- [[\\?\UNC\server\share\foo\..\..\..\bar]] --> "//?/UNC/server/share/bar"
 --- ```
 ---
 ---@since 10
-- 
cgit