8 files changed, 38 insertions, 23 deletions
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 4fe601dfd5..52a21587f4 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -190,12 +190,18 @@ function vim._os_proc_children(ppid)
   return children
 end
 
+--- @class vim.inspect.Opts
+--- @field depth? integer
+--- @field newline? string
+--- @field process? fun(item:any, path: string[]): any
+
 --- Gets a human-readable representation of the given object.
 ---
 ---@see |vim.print()|
 ---@see https://github.com/kikito/inspect.lua
 ---@see https://github.com/mpeterv/vinspect
 ---@return string
+---@overload fun(x: any, opts?: vim.inspect.Opts): string
 vim.inspect = vim.inspect
 
 do
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 8c550fccdb..c9e2e302dc 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -2197,7 +2197,7 @@ vim.bo.ft = vim.bo.filetype
 --- Characters to fill the statuslines, vertical separators and special
 --- lines in the window.
 --- It is a comma-separated list of items.  Each item has a name, a colon
---- and the value of that item:
+--- and the value of that item: `E1511`
 ---
 ---   item		default		Used for ~
 ---   stl		' '		statusline of the current window
@@ -2238,7 +2238,7 @@ vim.bo.ft = vim.bo.filetype
 ---
 --- For the "stl", "stlnc", "foldopen", "foldclose" and "foldsep" items
 --- single-byte and multibyte characters are supported.  But double-width
---- characters are not supported.
+--- characters are not supported. `E1512`
 ---
 --- The highlighting used for these items:
 ---   item		highlight group ~
@@ -3829,7 +3829,7 @@ vim.o.list = false
 vim.wo.list = vim.o.list
 
 --- Strings to use in 'list' mode and for the `:list` command.  It is a
---- comma-separated list of string settings.
+--- comma-separated list of string settings. *E1511*
 ---
 --- 						*lcs-eol*
 ---   eol:c		Character to show at the end of each line.  When
@@ -3921,7 +3921,7 @@ vim.wo.list = vim.o.list
 --- 		omitted.
 ---
 --- The characters ':' and ',' should not be used.  UTF-8 characters can
---- be used.  All characters must be single width.
+--- be used.  All characters must be single width. *E1512*
 ---
 --- Each character can be specified as hex:
 ---
diff --git a/runtime/lua/vim/diagnostic.lua b/runtime/lua/vim/diagnostic.lua
index c7a1e8ebd3..03a1fe9a2f 100644
--- a/runtime/lua/vim/diagnostic.lua
+++ b/runtime/lua/vim/diagnostic.lua
@@ -180,10 +180,8 @@ local all_namespaces = {}
 ---@return vim.diagnostic.Severity?
 local function to_severity(severity)
   if type(severity) == 'string' then
-    return assert(
-      M.severity[string.upper(severity)],
-      string.format('Invalid severity: %s', severity)
-    )
+    assert(M.severity[string.upper(severity)], string.format('Invalid severity: %s', severity))
+    return M.severity[string.upper(severity)]
   end
   return severity
 end
diff --git a/runtime/lua/vim/glob.lua b/runtime/lua/vim/glob.lua
index 49d6f555da..764200dd36 100644
--- a/runtime/lua/vim/glob.lua
+++ b/runtime/lua/vim/glob.lua
@@ -77,7 +77,8 @@ function M.to_lpeg(pattern)
   })
 
   local lpeg_pattern = p:match(pattern) --[[@as vim.lpeg.Pattern?]]
-  return assert(lpeg_pattern, 'Invalid glob')
+  assert(lpeg_pattern, 'Invalid glob')
+  return lpeg_pattern
 end
 
 return M
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index a63d5ba565..d720745110 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -181,7 +181,7 @@ end
 --- local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)
 --- ```
 ---
----@param f fun(...):bool Takes all values returned from the previous stage
+---@param f fun(...):boolean Takes all values returned from the previous stage
 ---                       in the pipeline and returns false or nil if the
 ---                       current iterator element should be removed.
 ---@return Iter
@@ -884,7 +884,7 @@ end
 
 --- Returns true if any of the items in the iterator match the given predicate.
 ---
----@param pred fun(...):bool Predicate function. Takes all values returned from the previous
+---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
 ---                          stage in the pipeline as arguments and returns true if the
 ---                          predicate matches.
 function Iter.any(self, pred)
@@ -908,7 +908,7 @@ end
 
 --- Returns true if all items in the iterator match the given predicate.
 ---
----@param pred fun(...):bool Predicate function. Takes all values returned from the previous
+---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
 ---                          stage in the pipeline as arguments and returns true if the
 ---                          predicate matches.
 function Iter.all(self, pred)
@@ -1106,7 +1106,7 @@ end
 ---
 ---@see |Iter:filter()|
 ---
----@param f fun(...):bool Filter function. Accepts the current iterator or table values as
+---@param f fun(...):boolean Filter function. Accepts the current iterator or table values as
 ---                       arguments and returns true if those values should be kept in the
 ---                       final table
 ---@param src table|function Table or iterator function to filter
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index a02a93d559..f3448209ba 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -488,8 +488,7 @@ end
 --- See |vim.lsp.start_client()| for all available options. The most important are:
 ---
 --- - `name` arbitrary name for the LSP client. Should be unique per language server.
---- - `cmd` command (in list form) used to start the language server. Must be absolute, or found on
----   `$PATH`. Shell constructs like `~` are not expanded.
+--- - `cmd` command string[] or function, described at |vim.lsp.start_client()|.
 --- - `root_dir` path to the project root. By default this is used to decide if an existing client
 ---   should be re-used. The example above uses |vim.fs.find()| and |vim.fs.dirname()| to detect the
 ---   root by traversing the file system upwards starting from the current directory until either
@@ -666,13 +665,13 @@ end
 --- Field `cmd` in {config} is required.
 ---
 ---@param config (lsp.ClientConfig) Configuration for the server:
---- - cmd: (string[]|fun(dispatchers: table):table) command a list of
----       strings treated like |jobstart()|. The command must launch the language server
----       process. `cmd` can also be a function that creates an RPC client.
----       The function receives a dispatchers table and must return a table with the
----       functions `request`, `notify`, `is_closing` and `terminate`
----       See |vim.lsp.rpc.request()| and |vim.lsp.rpc.notify()|
----       For TCP there is a built-in rpc client factory: |vim.lsp.rpc.connect()|
+--- - cmd: (string[]|fun(dispatchers: table):table) command string[] that launches the language
+---       server (treated as in |jobstart()|, must be absolute or on `$PATH`, shell constructs like
+---       "~" are not expanded), or function that creates an RPC client. Function receives
+---       a `dispatchers` table and returns a table with member functions `request`, `notify`,
+---       `is_closing` and `terminate`.
+---       See |vim.lsp.rpc.request()|, |vim.lsp.rpc.notify()|.
+---       For TCP there is a builtin RPC client factory: |vim.lsp.rpc.connect()|
 ---
 --- - cmd_cwd: (string, default=|getcwd()|) Directory to launch
 ---       the `cmd` process. Not related to `root_dir`.
diff --git a/runtime/lua/vim/lsp/inlay_hint.lua b/runtime/lua/vim/lsp/inlay_hint.lua
index ce1680549e..4816b873ba 100644
--- a/runtime/lua/vim/lsp/inlay_hint.lua
+++ b/runtime/lua/vim/lsp/inlay_hint.lua
@@ -368,7 +368,13 @@ function M.is_enabled(bufnr)
   return bufstates[bufnr] and bufstates[bufnr].enabled or false
 end
 
---- Enable/disable/toggle inlay hints for a buffer
+--- Enables or disables inlay hints for a buffer.
+---
+--- To "toggle", pass the inverse of `is_enabled()`:
+---
+--- ```lua
+--- vim.lsp.inlay_hint.enable(0, not vim.lsp.inlay_hint.is_enabled())
+--- ```
 ---
 --- @param bufnr (integer|nil) Buffer handle, or 0 or nil for current
 --- @param enable (boolean|nil) true/nil to enable, false to disable
diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua
index a249a10f47..971c4449e8 100644
--- a/runtime/lua/vim/treesitter/languagetree.lua
+++ b/runtime/lua/vim/treesitter/languagetree.lua
@@ -757,6 +757,11 @@ end)
 ---@param alias string language or filetype name
 ---@return string? # resolved parser name
 local function resolve_lang(alias)
+  -- validate that `alias` is a legal language
+  if not (alias and alias:match('[%w_]+') == alias) then
+    return
+  end
+
   if has_parser(alias) then
     return alias
   end