docs: misc (#28609)

Closes https://github.com/neovim/neovim/issues/28484.
Closes https://github.com/neovim/neovim/issues/28719.

Co-authored-by: Chris <crwebb85@gmail.com>
Co-authored-by: Gregory Anders <greg@gpanders.com>
Co-authored-by: Jake B <16889000+jakethedev@users.noreply.github.com>
Co-authored-by: Jonathan Raines <jonathan.s.raines@gmail.com>
Co-authored-by: Yi Ming <ofseed@foxmail.com>
Co-authored-by: Zane Dufour <zane@znd4.me>
Co-authored-by: zeertzjq <zeertzjq@outlook.com>

runtime/lua/vim/filetype.lua

@@ -2312,7 +2312,6 @@ end
 --- vim.filetype.add {
 ---   pattern = {
 ---     ['.*'] = {
----       priority = -math.huge,
 ---       function(path, bufnr)
 ---         local content = vim.api.nvim_buf_get_lines(bufnr, 0, 1, false)[1] or ''
 ---         if vim.regex([[^#!.*\\<mine\\>]]):match_str(content) ~= nil then
@@ -2321,6 +2320,7 @@ end
 ---           return 'drawing'
 ---         end
 ---       end,
+---       { priority = -math.huge },
 ---     },
 ---   },
 --- }

runtime/lua/vim/iter.lua

@@ -466,7 +466,8 @@ end
 --- -- Get the "maximum" item of an iterable.
 --- vim.iter({ -99, -4, 3, 42, 0, 0, 7 })
 ---   :fold({}, function(acc, v)
----     acc.max = math.max(v, acc.max or v) return acc
+---     acc.max = math.max(v, acc.max or v)
+---     return acc
 ---   end) --> { max = 42 }
 --- ```
 ---

runtime/lua/vim/lsp.lua

@@ -897,12 +897,12 @@ end
 ---@param bufnr (integer) Buffer handle, or 0 for current.
 ---@param method (string) LSP method name
 ---@param params (table|nil) Parameters to send to the server
----@param handler fun(results: table<integer, {error: lsp.ResponseError, result: any}>) (function)
+---@param handler fun(results: table<integer, {error: lsp.ResponseError?, result: any}>) (function)
 --- Handler called after all requests are completed. Server results are passed as
 --- a `client_id:result` map.
 ---@return function cancel Function that cancels all requests.
 function lsp.buf_request_all(bufnr, method, params, handler)
-  local results = {} --- @type table<integer,{error:lsp.ResponseError, result:any}>
+  local results = {} --- @type table<integer,{error: lsp.ResponseError?, result: any}>
   local result_count = 0
   local expected_result_count = 0
 
@@ -940,7 +940,7 @@ end
 ---@param params table? Parameters to send to the server
 ---@param timeout_ms integer? Maximum time in milliseconds to wait for a result.
 ---                           (default: `1000`)
----@return table<integer, {err: lsp.ResponseError, result: any}>? result Map of client_id:request_result.
+---@return table<integer, {error: lsp.ResponseError?, result: any}>? result Map of client_id:request_result.
 ---@return string? err On timeout, cancel, or error, `err` is a string describing the failure reason, and `result` is nil.
 function lsp.buf_request_sync(bufnr, method, params, timeout_ms)
   local request_results ---@type table

runtime/lua/vim/lsp/buf.lua

@@ -503,7 +503,7 @@ function M.typehierarchy(kind)
 
   --- Merge results from multiple clients into a single table. Client-ID is preserved.
   ---
-  --- @param results table<integer, {error: lsp.ResponseError, result: lsp.TypeHierarchyItem[]?}>
+  --- @param results table<integer, {error: lsp.ResponseError?, result: lsp.TypeHierarchyItem[]?}>
   --- @return [integer, lsp.TypeHierarchyItem][]
   local function merge_results(results)
     local merged_results = {}
@@ -521,7 +521,7 @@ function M.typehierarchy(kind)
 
   local bufnr = api.nvim_get_current_buf()
   local params = util.make_position_params()
-  --- @param results table<integer, {error: lsp.ResponseError, result: lsp.TypeHierarchyItem[]?}>
+  --- @param results table<integer, {error: lsp.ResponseError?, result: lsp.TypeHierarchyItem[]?}>
   vim.lsp.buf_request_all(bufnr, ms.textDocument_prepareTypeHierarchy, params, function(results)
     local merged_results = merge_results(results)
     if #merged_results == 0 then

runtime/lua/vim/lsp/inlay_hint.lua

@@ -98,7 +98,7 @@ function M.on_inlayhint(err, result, ctx, _)
   api.nvim__redraw({ buf = bufnr, valid = true })
 end
 
---- |lsp-handler| for the method `textDocument/inlayHint/refresh`
+--- |lsp-handler| for the method `workspace/inlayHint/refresh`
 ---@param ctx lsp.HandlerContext
 ---@private
 function M.on_refresh(err, _, ctx, _)
@@ -368,6 +368,7 @@ api.nvim_set_decoration_provider(namespace, {
   end,
 })
 
+--- Query whether inlay hint is enabled in the {filter}ed scope
 --- @param filter vim.lsp.inlay_hint.enable.Filter
 --- @return boolean
 --- @since 12
@@ -391,7 +392,7 @@ end
 --- Buffer number, or 0 for current buffer, or nil for all.
 --- @field bufnr integer?
 
---- Enables or disables inlay hints for a buffer.
+--- Enables or disables inlay hints for the {filter}ed scope.
 ---
 --- To "toggle", pass the inverse of `is_enabled()`:
 ---

runtime/lua/vim/snippet.lua

@@ -539,7 +539,7 @@ end
 ---
 --- ```lua
 --- vim.keymap.set({ 'i', 's' }, '<Tab>', function()
----    if vim.snippet.jumpable(1) then
+---    if vim.snippet.active({ direction = 1 }) then
 ---      return '<cmd>lua vim.snippet.jump(1)<cr>'
 ---    else
 ---      return '<Tab>'