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>

13 files changed, 31 insertions, 38 deletions

diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt
index 42d6bcfae0..09db651614 100644
--- a/runtime/doc/change.txt
+++ b/runtime/doc/change.txt
@@ -281,10 +281,6 @@ gr{char}		Replace the virtual characters under the cursor with
 			that have a special meaning in Insert mode, such as
 			most CTRL-keys, cannot be used.
 
-							*gr-default*
-			Mapped to |vim.lsp.buf.references()| by default.
-			|default-mappings|
-
 						*digraph-arg*
 The argument for Normal mode commands like |r| and |t| is a single character.
 When 'cpo' doesn't contain the 'D' flag, this character can also be entered
diff --git a/runtime/doc/editorconfig.txt b/runtime/doc/editorconfig.txt
index c7011cfbba..aa4e150862 100644
--- a/runtime/doc/editorconfig.txt
+++ b/runtime/doc/editorconfig.txt
@@ -6,11 +6,11 @@
 ==============================================================================
 EditorConfig integration                                        *editorconfig*
 
-Nvim supports EditorConfig. When a file is opened, Nvim searches all parent
-directories of that file for ".editorconfig" files, parses them, and applies
-any properties that match the opened file. Think of it like 'modeline' for an
-entire (recursive) directory. For more information see
-https://editorconfig.org/.
+Nvim supports EditorConfig. When a file is opened, after running |ftplugin|s
+and |FileType| autocommands, Nvim searches all parent directories of that file
+for ".editorconfig" files, parses them, and applies any properties that match
+the opened file. Think of it like 'modeline' for an entire (recursive)
+directory. For more information see https://editorconfig.org/.
 
                                                *g:editorconfig* *b:editorconfig*
 
diff --git a/runtime/doc/faq.txt b/runtime/doc/faq.txt
index 09bf829512..ca1429c0f5 100644
--- a/runtime/doc/faq.txt
+++ b/runtime/doc/faq.txt
@@ -29,13 +29,6 @@ Use the stable (release) https://github.com/neovim/neovim/releases/latest
 version for a more predictable experience.
 
 
-CAN I USE RUBY-BASED VIM PLUGINS (E.G. LUSTYEXPLORER)? ~
-
-Yes, starting with Nvim 0.1.5 PR #4980
-https://github.com/neovim/neovim/pull/4980 the legacy Vim `if_ruby` interface
-is supported.
-
-
 CAN I USE LUA-BASED VIM PLUGINS (E.G. NEOCOMPLETE)? ~
 
 No. Starting with Nvim 0.2 PR #4411
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index e783b7e3de..584fef0ed2 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -694,8 +694,8 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
                       milliseconds to wait for a result.
 
     Return (multiple): ~
-        (`table<integer, {err: lsp.ResponseError, result: any}>?`) result Map
-        of client_id:request_result.
+        (`table<integer, {error: lsp.ResponseError?, result: any}>?`) result
+        Map of client_id:request_result.
         (`string?`) err On timeout, cancel, or error, `err` is a string
         describing the failure reason, and `result` is nil.
 
@@ -1589,7 +1589,7 @@ save({lenses}, {bufnr}, {client_id})                 *vim.lsp.codelens.save()*
 Lua module: vim.lsp.inlay_hint                                *lsp-inlay_hint*
 
 enable({enable}, {filter})                       *vim.lsp.inlay_hint.enable()*
-    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()`: >lua
         vim.lsp.inlay_hint.enable(not vim.lsp.inlay_hint.is_enabled())
@@ -1636,6 +1636,7 @@ get({filter})                                       *vim.lsp.inlay_hint.get()*
         • {inlay_hint} (`lsp.InlayHint`)
 
 is_enabled({filter})                         *vim.lsp.inlay_hint.is_enabled()*
+    Query whether inlay hint is enabled in the {filter}ed scope
 
     Note: ~
       • This API is pre-release (unstable).
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index e24f5dfc7e..f227420c75 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2673,7 +2673,6 @@ vim.filetype.add({filetypes})                             *vim.filetype.add()*
         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
@@ -2682,6 +2681,7 @@ vim.filetype.add({filetypes})                             *vim.filetype.add()*
                   return 'drawing'
                 end
               end,
+              { priority = -math.huge },
             },
           },
         }
@@ -4005,7 +4005,8 @@ Iter:fold({init}, {f})                                           *Iter:fold()*
         -- 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 }
 <
 
@@ -4346,7 +4347,7 @@ vim.snippet.jump({direction})                             *vim.snippet.jump()*
 
     You can use this function to navigate a snippet as follows: >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>'
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 42b6f4b14c..6045acf935 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -417,6 +417,7 @@ The following changes to existing APIs or features add new behavior.
   • 'shortmess' includes the "C" flag.
   • 'grepprg' uses the -H and -I flags for grep by default,
     and defaults to using ripgrep if available.
+  • "]d" and "[d" in Normal mode map to |vim.diagnostic.goto_next()| and
     |vim.diagnostic.goto_prev()|, respectively. |]d-default| |[d-default|
   • <C-W>d (and <C-W><C-D>) map to |vim.diagnostic.open_float()|
     |CTRL-W_d-default|
diff --git a/runtime/lua/editorconfig.lua b/runtime/lua/editorconfig.lua
index c93c928339..dcd7425c29 100644
--- a/runtime/lua/editorconfig.lua
+++ b/runtime/lua/editorconfig.lua
@@ -1,10 +1,9 @@
 --- @brief
---- Nvim supports EditorConfig. When a file is opened, Nvim searches all parent
---- directories of that file for ".editorconfig" files, parses them, and applies
---- any properties that match the opened file. Think of it like 'modeline' for an
---- entire (recursive) directory. For more information see
---- https://editorconfig.org/.
----
+--- Nvim supports EditorConfig. When a file is opened, after running |ftplugin|s
+--- and |FileType| autocommands, Nvim searches all parent directories of that file
+--- for ".editorconfig" files, parses them, and applies any properties that match
+--- the opened file. Think of it like 'modeline' for an entire (recursive)
+--- directory. For more information see https://editorconfig.org/.
 
 --- @brief [g:editorconfig]() [b:editorconfig]()
 ---
diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua
index d6f680b195..0ae0f9ca92 100644
--- a/runtime/lua/vim/filetype.lua
+++ b/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 },
 ---     },
 ---   },
 --- }
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 5f1e3b6386..06415773bc 100644
--- a/runtime/lua/vim/iter.lua
+++ b/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 }
 --- ```
 ---
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index e2af317823..8103ed4d21 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/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
diff --git a/runtime/lua/vim/lsp/buf.lua b/runtime/lua/vim/lsp/buf.lua
index e05acff3df..49833eaeec 100644
--- a/runtime/lua/vim/lsp/buf.lua
+++ b/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
diff --git a/runtime/lua/vim/lsp/inlay_hint.lua b/runtime/lua/vim/lsp/inlay_hint.lua
index effc69c67e..8d22859a80 100644
--- a/runtime/lua/vim/lsp/inlay_hint.lua
+++ b/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()`:
 ---
diff --git a/runtime/lua/vim/snippet.lua b/runtime/lua/vim/snippet.lua
index 8fe03b3882..2d95d4203d 100644
--- a/runtime/lua/vim/snippet.lua
+++ b/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>'