docs: misc #33330

runtime/doc/api.txt

@@ -2371,7 +2371,12 @@ nvim_buf_del_var({buffer}, {name})                        *nvim_buf_del_var()*
       • {name}    Variable name
 
 nvim_buf_delete({buffer}, {opts})                          *nvim_buf_delete()*
-    Deletes the buffer. See |:bwipeout|
+    Deletes a buffer and its metadata (like |:bwipeout|).
+
+    To get |:bdelete| behavior, reset 'buflisted' and pass `unload=true`: >lua
+        vim.bo.buflisted = false
+        vim.api.nvim_buf_delete(0, { unload = true })
+<
 
     Attributes: ~
         not allowed when |textlock| is active or in the |cmdwin|
@@ -2380,8 +2385,8 @@ nvim_buf_delete({buffer}, {opts})                          *nvim_buf_delete()*
     Parameters: ~
       • {buffer}  Buffer id, or 0 for current buffer
       • {opts}    Optional parameters. Keys:
-                  • force: Force deletion and ignore unsaved changes.
-                  • unload: Unloaded only, do not delete. See |:bunload|
+                  • force: Force deletion, ignore unsaved changes.
+                  • unload: Unloaded only (|:bunload|), do not delete.
 
 nvim_buf_detach({buffer})                                  *nvim_buf_detach()*
     Deactivates buffer-update events on the channel.

runtime/doc/change.txt

@@ -367,7 +367,7 @@ CTRL-A			Add [count] to the number or alphabetic character at
 							*v_g_CTRL-A*
 {Visual}g CTRL-A	Add [count] to the number or alphabetic character in
 			the highlighted text. If several lines are
-		        highlighted, each one will be incremented by an
+			highlighted, each one will be incremented by an
 			additional [count] (so effectively creating a
 			[count] incrementing sequence).
 			For Example, if you have this list of numbers:
@@ -1244,6 +1244,18 @@ mapped.  E.g. |%| is mapped by the matchit plugin.
    With each successive deletion or change, Vim shifts the previous contents
 of register 1 into register 2, 2 into 3, and so forth, losing the previous
 contents of register 9.
+							*yankring*
+To also store yanks (not only deletions) in registers 1-9, try this: >lua
+    -- Yank-ring: store yanked text in registers 1-9.
+    vim.api.nvim_create_autocmd('TextYankPost', {
+      callback = function()
+        if vim.v.event.operator == 'y' then
+          for i = 9, 1, -1 do -- Shift all numbered registers.
+            vim.fn.setreg(tostring(i), vim.fn.getreg(tostring(i - 1)))
+          end
+        end
+      end,
+    })
 
 3. Small delete register "-				*quote_-* *quote-*
 This register contains text from commands that delete less than one line,
@@ -1719,7 +1731,7 @@ B	When joining lines, don't insert a space between two multibyte
 j	Where it makes sense, remove a comment leader when joining lines.  For
 	example, joining:
 		int i;   // the index ~
-		         // in the list ~
+			 // in the list ~
 	Becomes:
 		int i;   // the index in the list ~
 							*fo-p*

runtime/doc/lsp.txt

@@ -752,6 +752,9 @@ buf_is_attached({bufnr}, {client_id})              *vim.lsp.buf_is_attached()*
 buf_notify({bufnr}, {method}, {params})                 *vim.lsp.buf_notify()*
     Send a notification to a server
 
+    Attributes: ~
+        Since: 0.5.0
+
     Parameters: ~
       • {bufnr}   (`integer?`) The number of the buffer
       • {method}  (`string`) Name of the request method
@@ -765,6 +768,9 @@ buf_request_all({bufnr}, {method}, {params}, {handler})
     Sends an async request for all active clients attached to the buffer and
     executes the `handler` callback with the combined result.
 
+    Attributes: ~
+        Since: 0.5.0
+
     Parameters: ~
       • {bufnr}    (`integer`) Buffer handle, or 0 for current.
       • {method}   (`string`) LSP method name
@@ -787,6 +793,9 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
     result. Parameters are the same as |vim.lsp.buf_request_all()| but the
     result is different. Waits a maximum of {timeout_ms}.
 
+    Attributes: ~
+        Since: 0.5.0
+
     Parameters: ~
       • {bufnr}       (`integer`) Buffer handle, or 0 for current.
       • {method}      (`string`) LSP method name
@@ -890,6 +899,9 @@ config({name}, {cfg})                                       *vim.lsp.config()*
       local cfg = vim.lsp.config.luals
 <
 
+    Attributes: ~
+        Since: 0.11.0
+
     Parameters: ~
       • {name}  (`string`)
       • {cfg}   (`vim.lsp.Config`) See |vim.lsp.Config|.
@@ -905,6 +917,9 @@ enable({name}, {enable})                                    *vim.lsp.enable()*
           vim.lsp.enable({'luals', 'pyright'})
 <
 
+    Attributes: ~
+        Since: 0.11.0
+
     Parameters: ~
       • {name}    (`string|string[]`) Name(s) of client(s) to enable.
       • {enable}  (`boolean?`) `true|nil` to enable, `false` to disable.
@@ -922,6 +937,9 @@ foldclose({kind}, {winid})                               *vim.lsp.foldclose()*
         })
 <
 
+    Attributes: ~
+        Since: 0.11.0
+
     Parameters: ~
       • {kind}   (`lsp.FoldingRangeKind`) Kind to close, one of "comment",
                  "imports" or "region".
@@ -986,8 +1004,8 @@ get_buffers_by_client_id({client_id})
         (`integer[]`) buffers list of buffer ids
 
 get_client_by_id({client_id})                     *vim.lsp.get_client_by_id()*
-    Gets a client by id, or nil if the id is invalid. The returned client may
-    not yet be fully initialized.
+    Gets a client by id, or nil if the id is invalid or the client was
+    stopped. The returned client may not yet be fully initialized.
 
     Parameters: ~
       • {client_id}  (`integer`) client id
@@ -998,6 +1016,9 @@ get_client_by_id({client_id})                     *vim.lsp.get_client_by_id()*
 get_clients({filter})                                  *vim.lsp.get_clients()*
     Get active clients.
 
+    Attributes: ~
+        Since: 0.10.0
+
     Parameters: ~
       • {filter}  (`table?`) Key-value pairs used to filter the returned
                   clients.
@@ -1085,6 +1106,9 @@ start({config}, {opts})                                      *vim.lsp.start()*
     use |:au|, |nvim_create_autocmd()| or put the call in a
     `ftplugin/<filetype_name>.lua` (See |ftplugin-name|)
 
+    Attributes: ~
+        Since: 0.8.0
+
     Parameters: ~
       • {config}  (`vim.lsp.ClientConfig`) Configuration for the server. See
                   |vim.lsp.ClientConfig|.

runtime/doc/nvim.txt

@@ -75,6 +75,8 @@ the same Nvim configuration on all of your machines, by creating
 ==============================================================================
 What next?                                                   *nvim-quickstart*
 
+See |lua-guide| for practical notes on using Lua to configure Nvim.
+
 If you are just trying out Nvim for a few minutes, and want to see the
 extremes of what it can do, try one of these popular "extension packs" or
 "distributions" (Note: Nvim is not affiliated with these projects, and does

runtime/lua/vim/_meta/api.lua

@@ -324,12 +324,18 @@ function vim.api.nvim_buf_del_user_command(buffer, name) end
 --- @param name string Variable name
 function vim.api.nvim_buf_del_var(buffer, name) end
 
---- Deletes the buffer. See `:bwipeout`
+--- Deletes a buffer and its metadata (like `:bwipeout`).
+---
+--- To get `:bdelete` behavior, reset 'buflisted' and pass `unload=true`:
+--- ```lua
+--- vim.bo.buflisted = false
+--- vim.api.nvim_buf_delete(0, { unload = true })
+--- ```
 ---
 --- @param buffer integer Buffer id, or 0 for current buffer
 --- @param opts vim.api.keyset.buf_delete Optional parameters. Keys:
---- - force:  Force deletion and ignore unsaved changes.
---- - unload: Unloaded only, do not delete. See `:bunload`
+--- - force:  Force deletion, ignore unsaved changes.
+--- - unload: Unloaded only (`:bunload`), do not delete.
 function vim.api.nvim_buf_delete(buffer, opts) end
 
 --- Gets a changed tick of a buffer

runtime/lua/vim/lsp.lua

@@ -355,6 +355,8 @@ end
 ---   local cfg = vim.lsp.config.luals
 ---   ```
 ---
+---@since 13
+---
 --- @param name string
 --- @param cfg vim.lsp.Config
 --- @diagnostic disable-next-line:assign-type-mismatch
@@ -547,6 +549,8 @@ end
 ---   vim.lsp.enable({'luals', 'pyright'})
 --- ```
 ---
+---@since 13
+---
 --- @param name string|string[] Name(s) of client(s) to enable.
 --- @param enable? boolean `true|nil` to enable, `false` to disable.
 function lsp.enable(name, enable)
@@ -635,6 +639,8 @@ end
 --- Either use |:au|, |nvim_create_autocmd()| or put the call in a
 --- `ftplugin/<filetype_name>.lua` (See |ftplugin-name|)
 ---
+--- @since 10
+---
 --- @param config vim.lsp.ClientConfig Configuration for the server.
 --- @param opts vim.lsp.start.Opts? Optional keyword arguments.
 --- @return integer? client_id
@@ -1016,7 +1022,7 @@ function lsp.buf_is_attached(bufnr, client_id)
   return lsp.get_clients({ bufnr = bufnr, id = client_id, _uninitialized = true })[1] ~= nil
 end
 
---- Gets a client by id, or nil if the id is invalid.
+--- Gets a client by id, or nil if the id is invalid or the client was stopped.
 --- The returned client may not yet be fully initialized.
 ---
 ---@param client_id integer client id
@@ -1088,6 +1094,8 @@ end
 
 --- Get active clients.
 ---
+---@since 12
+---
 ---@param filter? vim.lsp.get_clients.Filter
 ---@return vim.lsp.Client[]: List of |vim.lsp.Client| objects
 function lsp.get_clients(filter)
@@ -1235,6 +1243,8 @@ end
 --- Sends an async request for all active clients attached to the buffer and executes the `handler`
 --- callback with the combined result.
 ---
+---@since 7
+---
 ---@param bufnr (integer) Buffer handle, or 0 for current.
 ---@param method (string) LSP method name
 ---@param params? table|(fun(client: vim.lsp.Client, bufnr: integer): table?) Parameters to send to the server.
@@ -1272,6 +1282,8 @@ end
 --- Parameters are the same as |vim.lsp.buf_request_all()| but the result is
 --- different. Waits a maximum of {timeout_ms}.
 ---
+---@since 7
+---
 ---@param bufnr integer Buffer handle, or 0 for current.
 ---@param method string LSP method name
 ---@param params? table|(fun(client: vim.lsp.Client, bufnr: integer): table?) Parameters to send to the server.
@@ -1301,6 +1313,9 @@ function lsp.buf_request_sync(bufnr, method, params, timeout_ms)
 end
 
 --- Send a notification to a server
+---
+---@since 7
+---
 ---@param bufnr (integer|nil) The number of the buffer
 ---@param method (string) Name of the request method
 ---@param params (any) Arguments to send to the server
@@ -1456,6 +1471,8 @@ end
 --- })
 --- ```
 ---
+---@since 13
+---
 ---@param kind lsp.FoldingRangeKind Kind to close, one of "comment", "imports" or "region".
 ---@param winid? integer Defaults to the current window.
 function lsp.foldclose(kind, winid)

src/gen/gen_help_html.lua

@@ -72,6 +72,7 @@ local new_layout = {
   ['gui.txt'] = true,
   ['intro.txt'] = true,
   ['lua.txt'] = true,
+  ['lua-guide.txt'] = true,
   ['luaref.txt'] = true,
   ['news.txt'] = true,
   ['news-0.9.txt'] = true,

src/nvim/api/buffer.c

@@ -1002,12 +1002,18 @@ Boolean nvim_buf_is_loaded(Buffer buffer)
   return buf && buf->b_ml.ml_mfp != NULL;
 }
 
-/// Deletes the buffer. See |:bwipeout|
+/// Deletes a buffer and its metadata (like |:bwipeout|).
+///
+/// To get |:bdelete| behavior, reset 'buflisted' and pass `unload=true`:
+/// ```lua
+/// vim.bo.buflisted = false
+/// vim.api.nvim_buf_delete(0, { unload = true })
+/// ```
 ///
 /// @param buffer Buffer id, or 0 for current buffer
 /// @param opts  Optional parameters. Keys:
-///          - force:  Force deletion and ignore unsaved changes.
-///          - unload: Unloaded only, do not delete. See |:bunload|
+///          - force:  Force deletion, ignore unsaved changes.
+///          - unload: Unloaded only (|:bunload|), do not delete.
 void nvim_buf_delete(Buffer buffer, Dict(buf_delete) *opts, Error *err)
   FUNC_API_SINCE(7)
   FUNC_API_TEXTLOCK