docs: misc

runtime/lua/vim/_core/editor.lua

@@ -336,6 +336,9 @@ local VIM_CMD_ARG_MAX = 20
 ---
 --- -- Ex command :vertical resize +2
 --- vim.cmd.resize({ '+2', mods = { vertical = true } })
+---
+--- -- Pass arg literally, without needing to escape special chars:
+--- vim.cmd.edit({ '%foo"|bar#baz"', magic = { file = false, bar = false } })
 --- ```
 ---
 ---@diagnostic disable-next-line: undefined-doc-param

runtime/lua/vim/_meta/api.lua

@@ -853,25 +853,32 @@ function vim.api.nvim_chan_send(chan, data) end
 ---     - NOTE: If not passed, will only delete autocmds *not* in any group.
 function vim.api.nvim_clear_autocmds(opts) end
 
---- Executes an Ex command.
+--- Executes an Ex command `cmd`, specified as a Dict with the same structure as returned by
+--- `nvim_parse_cmd()`.
 ---
---- Unlike `nvim_command()` this command takes a structured Dict instead of a String. This
---- allows for easier construction and manipulation of an Ex command. This also allows for things
---- such as having spaces inside a command argument, expanding filenames in a command that otherwise
---- doesn't expand filenames, etc. Command arguments may also be Number, Boolean or String.
+--- Use `magic={…=false}` to disable special chars:
+--- ```lua
+--- vim.api.nvim_cmd({
+---     cmd = 'edit',
+---     args = { '%foo"|bar#baz"' },
+---     magic = { file = false, bar = false }
+---   },
+---   {}
+--- )
+--- ```
 ---
---- The first argument may also be used instead of count for commands that support it in order to
---- make their usage simpler with `vim.cmd()`. For example, instead of
---- `vim.cmd.bdelete{ count = 2 }`, you may do `vim.cmd.bdelete(2)`.
+--- - See `nvim_parse_cmd()` to parse a cmdline string (which can then be passed to `nvim_cmd`).
+--- - See `nvim_command()` to execute a cmdline string.
 ---
 --- On execution error: fails with Vimscript error, updates v:errmsg.
 ---
 ---
---- @see vim.api.nvim_exec2
 --- @see vim.api.nvim_command
---- @param cmd vim.api.keyset.cmd Command to execute. Must be a Dict that can contain the same values as
---- the return value of `nvim_parse_cmd()` except "addr", "nargs" and "nextcmd"
---- which are ignored if provided. All values except for "cmd" are optional.
+--- @see vim.api.nvim_exec2
+--- @see vim.api.nvim_parse_cmd
+--- @param cmd vim.api.keyset.cmd Command to execute, a Dict with the same structure as the return value of
+--- `nvim_parse_cmd()` (except "addr", "nargs" and "nextcmd" are ignored).
+--- All keys except "cmd" are optional.
 --- @param opts vim.api.keyset.cmd_opts Optional parameters.
 --- - output: (boolean, default false) Whether to return command output.
 --- @return string # Command output (non-error, non-shell |:!|) if `output` is true, else empty string.

runtime/lua/vim/_meta/vimfn.lua

@@ -1368,6 +1368,8 @@ function vim.fn.debugbreak(pid) end
 --- @return T
 function vim.fn.deepcopy(expr, noref) end
 
+--- Lua: see |vim.fs.rm()|.
+---
 --- Without {flags} or with {flags} empty: Deletes the file by the
 --- name {fname}.
 ---
@@ -1853,7 +1855,7 @@ function vim.fn.exp(expr) end
 ---       current script ID  |<SID>|
 ---   <script>  Sourced script file, or script file
 ---       where the current function was defined.
----       For Lua see |lua-script-location|.
+---       Lua: see |lua-script-location|.
 ---   <stack>    Call stack
 ---   <cword>    Word under the cursor
 ---   <cWORD>    WORD under the cursor
@@ -4949,7 +4951,7 @@ function vim.fn.jobresize(job, width, height) end
 --- @return any
 function vim.fn.jobsend(...) end
 
---- Note: Prefer |vim.system()| in Lua (unless using `rpc`, `pty`, or `term`).
+--- Lua: Prefer |vim.system()| (unless using `rpc`, `pty`, or `term`).
 ---
 --- Spawns {cmd} as a job.
 --- If {cmd} is a List it runs directly (no 'shell').
@@ -10164,7 +10166,7 @@ function vim.fn.synconcealed(lnum, col) end
 --- @return integer[]
 function vim.fn.synstack(lnum, col) end
 
---- Note: Prefer |vim.system()| in Lua.
+--- Lua: Prefer |vim.system()|.
 ---
 --- Gets the output of {cmd} as a |string| (|systemlist()| returns
 --- a |List|) and sets |v:shell_error| to the error code.
@@ -10644,7 +10646,7 @@ function vim.fn.undofile(name) end
 --- @return vim.fn.undotree.ret
 function vim.fn.undotree(buf) end
 
---- Note: Prefer |vim.list.unique()| in Lua.
+--- Lua: Prefer |vim.list.unique()|.
 ---
 --- Remove second and succeeding copies of repeated adjacent
 --- {list} items in-place.  Returns {list}.  If you want a list
@@ -11042,7 +11044,7 @@ function vim.fn.wincol() end
 --- is "10.0", Windows 8 is "6.2", Windows XP is "5.1".  For
 --- non-MS-Windows systems the result is an empty string.
 ---
---- See also Lua |uv.os_uname()|.
+--- Lua: see |uv.os_uname()|.
 ---
 --- @return string
 function vim.fn.windowsversion() end