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>

24 files changed, 48 insertions, 57 deletions

diff --git a/INSTALL.md b/INSTALL.md
index 0e7208a782..adbb116153 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -36,7 +36,7 @@ Windows 8+ is required. Windows 7 or older is not supported.
 
 ### [Chocolatey](https://chocolatey.org)
 
-- **Release (v0.7):** `choco install neovim` (use -y for automatically skipping confirmation messages)
+- **Latest Release:** `choco install neovim` (use -y for automatically skipping confirmation messages)
 - **Development (pre-release):** `choco install neovim --pre`
 
 ### [Scoop](https://scoop.sh/)
diff --git a/MAINTAIN.md b/MAINTAIN.md
index 10c7baef06..5cb97fb81b 100644
--- a/MAINTAIN.md
+++ b/MAINTAIN.md
@@ -22,7 +22,7 @@ In practice we haven't found a way to forecast more precisely than "next" and
 * Next feature-release (1.x.0)
 
 The forecasting problem might be solved with an explicit priority system (like
-Bram's todo.txt). Meanwhile the Neovim priority system is defined by:
+Vim's todo.txt). Meanwhile the Neovim priority system is defined by:
 
 * PRs nearing completion.
 * Issue labels. E.g. the `has:plan` label increases the ticket's priority merely
@@ -57,8 +57,8 @@ has a major bug:
 
 ### Release automation
 
-Neovim automation includes a [backport bot](https://github.com/zeebe-io/backport-action).
-Trigger the action by labeling a PR with `backport release-X.Y`. See `.github/workflows/backport.yml`.
+Neovim automation includes a [backport bot](https://github.com/korthout/backport-action).
+Trigger the action by labeling a PR with `ci:backport release-x.y`. See `.github/workflows/backport.yml`.
 
 Deprecating and removing features
 ---------------------------------
@@ -74,7 +74,7 @@ When a (non-experimental) feature is slated to be removed it should:
 1. Be _soft_ deprecated in the _next_ release
   - Use of the deprecated feature will still work.
   - This means deprecating via documentation and annotation (`@deprecated`).
-  - Include a note in `news.txt` under `DEPRECATIONS`.
+  - Include a note in `deprecated.txt`.
   - For Lua features, use `vim.deprecate()`. The specified version is the
     current minor version + 2. For example, if the current version is
     `v0.10.0-dev-1957+gd676746c33` then use `0.12`.
@@ -132,7 +132,7 @@ Some can be auto-bumped by `scripts/bump_deps.lua`.
 * [gettext](https://ftp.gnu.org/pub/gnu/gettext/)
 * [libiconv](https://ftp.gnu.org/pub/gnu/libiconv)
 * [libuv](https://github.com/libuv/libuv)
-* [libvterm](http://www.leonerd.org.uk/code/libvterm/)
+* [libvterm](https://www.leonerd.org.uk/code/libvterm/)
   * Downloading from the original source is unreliable, so we use our [mirror](https://github.com/neovim/libvterm) instead.
 * [lua-compat](https://github.com/keplerproject/lua-compat-5.3)
 * [tree-sitter](https://github.com/tree-sitter/tree-sitter)
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>'
diff --git a/src/nvim/cursor.c b/src/nvim/cursor.c
index 91bd217ae8..2e9e68843a 100644
--- a/src/nvim/cursor.c
+++ b/src/nvim/cursor.c
@@ -353,7 +353,7 @@ void check_cursor_col(win_T *win)
     // Allow cursor past end-of-line when:
     // - in Insert mode or restarting Insert mode
     // - in Visual mode and 'selection' isn't "old"
-    // - 'virtualedit' is set */
+    // - 'virtualedit' is set
     if ((State & MODE_INSERT) || restart_edit
         || (VIsual_active && *p_sel != 'o')
         || (cur_ve_flags & VE_ONEMORE)
diff --git a/src/nvim/ex_docmd.c b/src/nvim/ex_docmd.c
index 47b4c1e47d..fb4acaec04 100644
--- a/src/nvim/ex_docmd.c
+++ b/src/nvim/ex_docmd.c
@@ -4082,7 +4082,7 @@ void separate_nextcmd(exarg_T *eap)
         break;
       }
     } else if (
-               // Check for '"': start of comment or '|': next command */
+               // Check for '"': start of comment or '|': next command
                // :@" does not start a comment!
                // :redir @" doesn't either.
                (*p == '"'
diff --git a/src/nvim/grid.c b/src/nvim/grid.c
index 24a82b7e78..56246bf001 100644
--- a/src/nvim/grid.c
+++ b/src/nvim/grid.c
@@ -443,7 +443,7 @@ int grid_line_puts(int col, const char *text, int textlen, int attr)
 
     if (col + mbyte_cells > max_col) {
       // Only 1 cell left, but character requires 2 cells:
-      // display a '>' in the last column to avoid wrapping. */
+      // display a '>' in the last column to avoid wrapping.
       schar = schar_from_ascii('>');
       mbyte_cells = 1;
     }
diff --git a/src/nvim/highlight_group.c b/src/nvim/highlight_group.c
index c4fb57c95a..1c47791a65 100644
--- a/src/nvim/highlight_group.c
+++ b/src/nvim/highlight_group.c
@@ -1963,7 +1963,7 @@ int syn_name2id_len(const char *name, size_t len)
     return 0;
   }
 
-  // Avoid using stricmp() too much, it's slow on some systems */
+  // Avoid using stricmp() too much, it's slow on some systems
   // Avoid alloc()/free(), these are slow too.
   vim_memcpy_up(name_u, name, len);
   name_u[len] = '\0';
diff --git a/src/nvim/indent_c.c b/src/nvim/indent_c.c
index a660c9dead..65b5f46333 100644
--- a/src/nvim/indent_c.c
+++ b/src/nvim/indent_c.c
@@ -1197,7 +1197,7 @@ static int cin_is_cpp_baseclass(cpp_baseclass_cache_T *cached)
       s = line;
     }
     if (s == line) {
-      // don't recognize "case (foo):" as a baseclass */
+      // don't recognize "case (foo):" as a baseclass
       if (cin_iscase(s, false)) {
         break;
       }
diff --git a/src/nvim/mapping.c b/src/nvim/mapping.c
index ad02a060a2..9320390d68 100644
--- a/src/nvim/mapping.c
+++ b/src/nvim/mapping.c
@@ -1812,8 +1812,7 @@ int makemap(FILE *fd, buf_T *buf)
           iemsg(_("E228: makemap: Illegal mode"));
           return FAIL;
         }
-        do {
-          // do this twice if c2 is set, 3 times with c3 */
+        do {  // do this twice if c2 is set, 3 times with c3
           // When outputting <> form, need to make sure that 'cpo'
           // is set to the Vim default.
           if (!did_cpo) {
diff --git a/src/nvim/path.c b/src/nvim/path.c
index 251051a4ac..f7e8b2b65c 100644
--- a/src/nvim/path.c
+++ b/src/nvim/path.c
@@ -999,7 +999,7 @@ static void uniquefy_paths(garray_T *gap, char *pattern)
       memmove(path, path_cutoff, strlen(path_cutoff) + 1);
     } else {
       // Here all files can be reached without path, so get shortest
-      // unique path.  We start at the end of the path. */
+      // unique path.  We start at the end of the path.
       char *pathsep_p = path + len - 1;
       while (find_previous_pathsep(path, &pathsep_p)) {
         if (vim_regexec(&regmatch, pathsep_p + 1, 0)
diff --git a/src/nvim/regexp.c b/src/nvim/regexp.c
index e923449abe..77724b629d 100644
--- a/src/nvim/regexp.c
+++ b/src/nvim/regexp.c
@@ -10555,7 +10555,7 @@ nfa_do_multibyte:
       // NFA_END_COMPOSING is the ). Note that right now we are
       // building the postfix form, not the NFA itself;
       // a composing char could be: a, b, c, NFA_COMPOSING
-      // where 'b' and 'c' are chars with codes > 256. */
+      // where 'b' and 'c' are chars with codes > 256.
       while (true) {
         EMIT(c);
         if (i > 0) {
diff --git a/src/nvim/search.c b/src/nvim/search.c
index 1720274e61..df0a9171d2 100644
--- a/src/nvim/search.c
+++ b/src/nvim/search.c
@@ -2460,7 +2460,7 @@ int current_search(int count, bool forward)
     // beginning of the file (cursor might be on the search match)
     // except when Visual mode is active, so that extending the visual
     // selection works.
-    if (i == 1 && !result) {  // not found, abort */
+    if (i == 1 && !result) {  // not found, abort
       curwin->w_cursor = orig_pos;
       if (VIsual_active) {
         VIsual = save_VIsual;
@@ -3677,9 +3677,8 @@ void find_pattern_in_path(char *ptr, Direction dir, size_t len, bool whole, bool
                                 true) & kEqualFiles) {
             if (type != CHECK_PATH
                 && action == ACTION_SHOW_ALL && files[i].matched) {
-              msg_putchar('\n');  // cursor below last one */
-              if (!got_int) {  // don't display if 'q' typed at "--more--"
-                               // message
+              msg_putchar('\n');  // cursor below last one
+              if (!got_int) {  // don't display if 'q' typed at "--more--" message
                 msg_home_replace_hl(new_fname);
                 msg_puts(_(" (includes previously listed match)"));
                 prev_fname = NULL;