docs: misc, :bcd, slug()

runtime/lua/vim/fs.lua

@@ -147,39 +147,33 @@ function M.joinpath(...)
   return (path:gsub(iswin and '[/\\][/\\]*' or '//+', '/'))
 end
 
---- Generates a bounded, filesystem-safe filename from an arbitrary identity string.
+--- Gets a filesystem-safe, mnemonic slug (readable prefix + short hash) of an arbitrary filepath or
+--- other "identity string".
 ---
---- - The input is normalized via |vim.fs.normalize()| so that equivalent paths produce the same
----   result (e.g., `~/foo` and `/home/username/foo`).
---- - `$HOME` is replaced with `~`. On Windows, UNC paths are replaced with `=unc-`.
---- - An 8-character hex hash (|sha256()|) of the normalized input is appended to prevent
----   collisions.
---- - Unsafe characters (`/ \ : * ? " < > |`, whitespace, control characters) are replaced with
----   `-`, and trailing `-` and `.` are stripped.
+--- - The input is normalized so equivalent paths produce the same result.
+--- - A hash of the normalized input is appended to prevent collisions.
+--- - Unsafe chars are replaced with "-".
+--- - `$HOME` is replaced with "~".
+--- - UNC paths (Windows) are prefixed with "=unc-".
 --- - If `opts.maxlen` is exceeded, the result will be truncated to `{head}~~~{tail}-{hash8}`.
 --- - If the sanitized name is empty, the reserved label `=special` will be used.
 ---
 --- Examples:
 ---
 --- ```lua
---- vim.fs.slug('/tmp/test/foo.md')
----    --> "tmp-test-foo.md-{hash}"
----
---- vim.fs.slug('C:/src/project/main.c')
----    --> "C--src-project-main.c-{hash}"
----
---- vim.fs.slug(('/a/very/long/path'):rep(10) .. '/file.txt', { maxlen = 60 })
+--- vim.print(vim.fs.slug('/tmp/test/foo.md'))           --> "tmp-test-foo.md-{hash}"
+--- vim.print(vim.fs.slug('C:/src/project/main.c'))      --> "C--src-project-main.c-{hash}"
+--- vim.print(vim.fs.slug(vim.fn.expand('~/file.txt')))  --> "~-file.txt-{hash}"
+--- vim.print(vim.fs.slug('---'))                        --> "=special-{hash}"
+--- vim.print(vim.fs.slug(('/a/very/long/path'):rep(10) .. '/file.txt', { maxlen = 60 }))
 ---    --> "a-very-long-~~~-path-a-very-long-path-file.txt-{hash}"
----
---- vim.fs.slug('home/username/file.txt')
----    --> "~-file.txt-{hash}"
 --- ```
 ---
 ---@since 15
----@param path string a string that is not filesystem-safe.
----@param opts? table Optional parameters:
----  - maxlen: (integer) Max byte length of the result. Default is 180. Value must be at least 8.
----@return string # Filesystem-safe file name
+---@param path string Filepath (or other identity string).
+---@param opts? table
+---  - maxlen: (integer, default: 180) Max length (bytes) of the result.
+---@return string # Filesystem-safe, mnemonic slug.
 function M.slug(path, opts)
   vim.validate('path', path, 'string')
   opts = opts or {}
@@ -188,7 +182,7 @@ function M.slug(path, opts)
       return true
     end
     return type(v) == 'number' and v >= 8
-  end, '`opt.maxlen` must be at least 8')
+  end, '`opt.maxlen` must be >= 8')
   opts.maxlen = opts.maxlen or 180
 
   -- Normalize before computing the hash so equivalent paths produce the same result