docs: misc, :bcd, slug()

runtime/lua/vim/_meta/api.gen.lua

@@ -2415,10 +2415,15 @@ function vim.api.nvim_win_del_var(win, name) end
 --- @return integer # Buffer id
 function vim.api.nvim_win_get_buf(win) end
 
---- Gets window configuration in the form of a dict which can be passed as the `config` parameter of
---- `nvim_open_win()`.
+--- Gets window config as a dict which can be passed to `nvim_open_win()` as the `config` parameter.
 ---
---- For non-floating windows, `relative` is empty.
+--- For non-floating windows, `relative` is empty, thus you can check that field to detect if
+--- a window is a floatwin:
+--- ```lua
+--- vim.print(vim.api.nvim_win_get_config(0).relative == '' and 'non-float' or 'float')
+--- -- Or use win_gettype().
+--- vim.print(vim.fn.win_gettype())
+--- ```
 ---
 --- @param win integer `window-ID`, or 0 for current window
 --- @return vim.api.keyset.win_config_ret # Map defining the window configuration, see |nvim_open_win()|

runtime/lua/vim/_meta/vimfn.gen.lua

@@ -827,7 +827,7 @@ function vim.fn.chanclose(id, stream) end
 --- @return integer
 function vim.fn.changenr() end
 
---- Lua: Prefer |nvim_chan_send()| for string data; list input and the return value differ.
+--- Lua: Prefer |nvim_chan_send()| for string (binary) data.
 ---
 --- Send data to channel {id}. For a job, it writes it to the
 --- stdin of the process. For the stdio channel |channel-stdio|,
@@ -836,9 +836,12 @@ function vim.fn.changenr() end
 --- See |channel-bytes| for more information.
 ---
 --- {data} may be a string, string convertible, |Blob|, or a list.
+---
 --- If {data} is a list, the items will be joined by newlines; any
---- newlines in an item will be sent as NUL. To send a final
---- newline, include a final empty string. Example: >vim
+--- newlines in an item will be sent as NUL; to send a final
+--- newline, include a final empty string. |NL-used-for-Nul|
+---
+--- Example: >vim
 ---   call chansend(id, ["abc", "123\n456", ""])
 --- <will send "abc<NL>123<NUL>456<NL>".
 ---
@@ -848,7 +851,7 @@ function vim.fn.changenr() end
 ---
 --- @param id number
 --- @param data string|string[]
---- @return 0|1
+--- @return integer
 function vim.fn.chansend(id, data) end
 
 --- Lua: Prefer |string.byte()|: only works with ASCII.
@@ -11355,22 +11358,18 @@ function vim.fn.win_findbuf(bufnr) end
 --- @return integer
 function vim.fn.win_getid(win, tab) end
 
---- Return the type of the window:
----   "autocmd"  autocommand window.  Temporary window
----       used to execute autocommands.
----   "command"  command-line window |cmdwin|
----   (empty)    normal window
----   "loclist"  |location-list-window|
----   "popup"    floating window |api-floatwin|
----   "preview"  preview window |preview-window|
----   "quickfix"  |quickfix-window|
----   "unknown"  window {nr} not found
+--- Gets the type of the given window, or current window if {nr}
+--- is omitted:
+--- - (empty)     Normal window
+--- - "autocmd"   Internal "context-switch" window.
+--- - "command"   Command-line window |cmdwin|
+--- - "loclist"   |location-list-window|
+--- - "popup"     Floating window |api-floatwin|
+--- - "preview"   Preview window |preview-window|
+--- - "quickfix"  |quickfix-window|
+--- - "unknown"   Window {nr} not found
 ---
---- When {nr} is omitted return the type of the current window.
---- When {nr} is given (|window-number| or |window-ID|) return the
---- type of that window.
----
---- Also see the 'buftype' option.
+--- See also the 'buftype' option.
 ---
 --- @param nr? integer
 --- @return 'autocmd'|'command'|''|'loclist'|'popup'|'preview'|'quickfix'|'unknown'

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