aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJustin M. Keyes <justinkz@gmail.com>2025-03-17 04:59:31 -0700
committerGitHub <noreply@github.com>2025-03-17 04:59:31 -0700
commit5440e59247b690e990244be793b1ffd1cb5b8e80 (patch)
treef508a3c9ae52ac10d682625201ec16e8d9fd7887
parentd0cda9d6c59d88314b67f251a1c13216424aebcf (diff)
parentf96606371c13fd10280d737a4e3e2ae9149c2067 (diff)
downloadrneovim-5440e59247b690e990244be793b1ffd1cb5b8e80.tar.gz
rneovim-5440e59247b690e990244be793b1ffd1cb5b8e80.tar.bz2
rneovim-5440e59247b690e990244be793b1ffd1cb5b8e80.zip
Merge #32810 docs
Diffstat
-rw-r--r--.editorconfig2
-rw-r--r--runtime/doc/api.txt101
-rw-r--r--runtime/doc/autocmd.txt11
-rw-r--r--runtime/doc/intro.txt2
-rw-r--r--runtime/doc/lsp.txt197
-rw-r--r--runtime/doc/motion.txt2
-rw-r--r--runtime/doc/options.txt9
-rw-r--r--runtime/doc/quickref.txt2
-rw-r--r--runtime/doc/terminal.txt8
-rw-r--r--runtime/doc/ui.txt36
-rw-r--r--runtime/doc/vvars.txt58
-rw-r--r--runtime/lua/vim/_meta/api.lua97
-rw-r--r--runtime/lua/vim/_meta/options.lua7
-rw-r--r--runtime/lua/vim/_meta/vvars.lua60
-rw-r--r--runtime/lua/vim/lsp/completion.lua2
-rw-r--r--src/nvim/api/buffer.c65
-rw-r--r--src/nvim/api/command.c6
-rw-r--r--src/nvim/api/deprecated.c28
-rw-r--r--src/nvim/api/extmark.c10
-rw-r--r--src/nvim/api/private/helpers.c2
-rw-r--r--src/nvim/api/vim.c14
-rw-r--r--src/nvim/api/window.c4
-rw-r--r--src/nvim/options.lua8
-rw-r--r--src/nvim/vvars.lua58
24 files changed, 416 insertions, 373 deletions
diff --git a/.editorconfig b/.editorconfig
index 6e551f77ad..0937a15167 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -10,7 +10,7 @@ insert_final_newline = true
[*.{c,h,in,lua}]
max_line_length = 100
-[src/nvim/eval.lua]
+[src/nvim/{eval,vvars}.lua]
max_line_length = 68
[*.py]
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index e096231724..4d368c6426 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -585,7 +585,7 @@ nvim_create_buf({listed}, {scratch}) *nvim_create_buf()*
buffer.
Return: ~
- Buffer handle, or 0 on error
+ Buffer id, or 0 on error
See also: ~
• buf_open_scratch
@@ -835,7 +835,7 @@ nvim_get_current_buf() *nvim_get_current_buf()*
Since: 0.1.0
Return: ~
- Buffer handle
+ Buffer id
nvim_get_current_line() *nvim_get_current_line()*
Gets the current line.
@@ -1087,7 +1087,7 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
• {col} Mouse column-position (zero-based, like redraw events)
nvim_list_bufs() *nvim_list_bufs()*
- Gets the current list of buffer handles
+ Gets the current list of buffers.
Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use
|nvim_buf_is_loaded()| to check if a buffer is loaded.
@@ -1096,7 +1096,7 @@ nvim_list_bufs() *nvim_list_bufs()*
Since: 0.1.0
Return: ~
- List of buffer handles
+ List of buffer ids
nvim_list_chans() *nvim_list_chans()*
Get information about all open channels.
@@ -1147,7 +1147,7 @@ nvim_list_uis() *nvim_list_uis()*
• "chan" |channel-id| of remote UI
nvim_list_wins() *nvim_list_wins()*
- Gets the current list of window handles.
+ Gets the current list of all |window-ID|s in all tabpages.
Attributes: ~
Since: 0.1.0
@@ -1384,7 +1384,7 @@ nvim_set_current_buf({buffer}) *nvim_set_current_buf()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer handle
+ • {buffer} Buffer id
nvim_set_current_dir({dir}) *nvim_set_current_dir()*
Changes the global working directory.
@@ -1416,7 +1416,7 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()*
• {tabpage} |tab-ID| to focus
nvim_set_current_win({window}) *nvim_set_current_win()*
- Sets the current window. Also changes tabpage, if necessary.
+ Sets the current window (and tabpage, implicitly).
Attributes: ~
not allowed when |textlock| is active or in the |cmdwin|
@@ -1880,7 +1880,7 @@ nvim_buf_create_user_command({buffer}, {name}, {command}, {opts})
Since: 0.7.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer.
+ • {buffer} Buffer id, or 0 for current buffer.
See also: ~
• nvim_create_user_command
@@ -1896,7 +1896,7 @@ nvim_buf_del_user_command({buffer}, {name})
Since: 0.7.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer.
+ • {buffer} Buffer id, or 0 for current buffer.
• {name} Name of the command to delete.
nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()*
@@ -1906,7 +1906,7 @@ nvim_buf_get_commands({buffer}, {opts}) *nvim_buf_get_commands()*
Since: 0.3.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {opts} Optional parameters. Currently not used.
Return: ~
@@ -2238,7 +2238,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
Since: 0.3.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {send_buffer} True if the initial notification should contain the
whole buffer: first notification will be
`nvim_buf_lines_event`. Else the first notification
@@ -2248,7 +2248,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
• on_lines: Lua callback invoked on change. Return a
truthy value (not `false` or `nil`) to detach. Args:
• the string "lines"
- • buffer handle
+ • buffer id
• b:changedtick
• first line that changed (zero-indexed)
• last line that was changed
@@ -2261,7 +2261,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
change compared to on_lines. Return a truthy value
(not `false` or `nil`) to detach. Args:
• the string "bytes"
- • buffer handle
+ • buffer id
• b:changedtick
• start row of the changed text (zero-indexed)
• start column of the changed text
@@ -2280,15 +2280,15 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
• on_changedtick: Lua callback invoked on changedtick
increment without text change. Args:
• the string "changedtick"
- • buffer handle
+ • buffer id
• b:changedtick
• on_detach: Lua callback invoked on detach. Args:
• the string "detach"
- • buffer handle
+ • buffer id
• on_reload: Lua callback invoked on reload. The entire
buffer content should be considered changed. Args:
• the string "reload"
- • buffer handle
+ • buffer id
• utf_sizes: include UTF-32 and UTF-16 size of the
replaced region, as args to `on_lines`.
• preview: also attach to command preview (i.e.
@@ -2320,7 +2320,7 @@ nvim_buf_call({buffer}, {fun}) *nvim_buf_call()*
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {fun} Function to call inside the buffer (currently Lua callable
only)
@@ -2334,7 +2334,7 @@ nvim_buf_del_keymap({buffer}, {mode}, {lhs}) *nvim_buf_del_keymap()*
Since: 0.4.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
See also: ~
• |nvim_del_keymap()|
@@ -2367,7 +2367,7 @@ nvim_buf_del_var({buffer}, {name}) *nvim_buf_del_var()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {name} Variable name
nvim_buf_delete({buffer}, {opts}) *nvim_buf_delete()*
@@ -2378,7 +2378,7 @@ nvim_buf_delete({buffer}, {opts}) *nvim_buf_delete()*
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {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|
@@ -2391,7 +2391,7 @@ nvim_buf_detach({buffer}) *nvim_buf_detach()*
Since: 0.3.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
Return: ~
False if detach failed (because the buffer isn't loaded); otherwise
@@ -2408,7 +2408,7 @@ nvim_buf_get_changedtick({buffer}) *nvim_buf_get_changedtick()*
Since: 0.2.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
Return: ~
`b:changedtick` value.
@@ -2420,12 +2420,12 @@ nvim_buf_get_keymap({buffer}, {mode}) *nvim_buf_get_keymap()*
Since: 0.2.1
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {mode} Mode short-name ("n", "i", "v", ...)
Return: ~
Array of |maparg()|-like dictionaries describing mappings. The
- "buffer" key holds the associated buffer handle.
+ "buffer" key holds the associated buffer id.
*nvim_buf_get_lines()*
nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
@@ -2442,7 +2442,7 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {start} First line index
• {end} Last line index, exclusive
• {strict_indexing} Whether out-of-bounds should be an error.
@@ -2450,6 +2450,9 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
Return: ~
Array of lines, or empty array for unloaded buffer.
+ See also: ~
+ • |nvim_buf_get_text()|
+
nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()*
Returns a `(row,col)` tuple representing the position of the named mark.
"End of line" column position is returned as |v:maxcol| (big number). See
@@ -2461,7 +2464,7 @@ nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {name} Mark name
Return: ~
@@ -2479,7 +2482,7 @@ nvim_buf_get_name({buffer}) *nvim_buf_get_name()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
Return: ~
Buffer name
@@ -2499,7 +2502,7 @@ nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()*
Since: 0.3.2
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {index} Line index
Return: ~
@@ -2508,10 +2511,8 @@ nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()*
*nvim_buf_get_text()*
nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
{opts})
- Gets a range from the buffer.
-
- This differs from |nvim_buf_get_lines()| in that it allows retrieving only
- portions of a line.
+ Gets a range from the buffer (may be partial lines, unlike
+ |nvim_buf_get_lines()|).
Indexing is zero-based. Row indices are end-inclusive, and column indices
are end-exclusive.
@@ -2522,7 +2523,7 @@ nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
Since: 0.7.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {start_row} First line index
• {start_col} Starting column (byte offset) on first line
• {end_row} Last line index, inclusive
@@ -2539,7 +2540,7 @@ nvim_buf_get_var({buffer}, {name}) *nvim_buf_get_var()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {name} Variable name
Return: ~
@@ -2553,7 +2554,7 @@ nvim_buf_is_loaded({buffer}) *nvim_buf_is_loaded()*
Since: 0.3.2
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
Return: ~
true if the buffer is valid and loaded, false otherwise.
@@ -2569,7 +2570,7 @@ nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
Return: ~
true if the buffer is valid, false otherwise.
@@ -2581,7 +2582,7 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
Return: ~
Line count, or 0 for unloaded buffer. |api-buffer|
@@ -2594,7 +2595,7 @@ nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {opts})
Since: 0.4.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
See also: ~
• |nvim_set_keymap()|
@@ -2605,7 +2606,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement})
Indexing is zero-based, end-exclusive. Negative indices are interpreted as
length+1+index: -1 refers to the index past the end. So to change or
- delete the last element use start=-2 and end=-1.
+ delete the last line use start=-2 and end=-1.
To insert lines at a given index, set `start` and `end` to the same index.
To delete a range of lines, set `replacement` to an empty array.
@@ -2618,7 +2619,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement})
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {start} First line index
• {end} Last line index, exclusive
• {strict_indexing} Whether out-of-bounds should be an error.
@@ -2661,7 +2662,7 @@ nvim_buf_set_name({buffer}, {name}) *nvim_buf_set_name()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {name} Buffer name
*nvim_buf_set_text()*
@@ -2691,7 +2692,7 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {start_row} First line index
• {start_col} Starting column (byte offset) on first line
• {end_row} Last line index, inclusive
@@ -2705,7 +2706,7 @@ nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()*
Since: 0.1.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {name} Variable name
• {value} Variable value
@@ -2725,7 +2726,7 @@ nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end})
Since: 0.3.2
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {ns_id} Namespace to clear, or -1 to clear all namespaces.
• {line_start} Start of range of lines to clear
• {line_end} End of range of lines to clear (exclusive) or -1 to
@@ -2738,7 +2739,7 @@ nvim_buf_del_extmark({buffer}, {ns_id}, {id}) *nvim_buf_del_extmark()*
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {ns_id} Namespace id from |nvim_create_namespace()|
• {id} Extmark id
@@ -2753,7 +2754,7 @@ nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts})
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {ns_id} Namespace id from |nvim_create_namespace()|
• {id} Extmark id
• {opts} Optional parameters. Keys:
@@ -2806,7 +2807,7 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {ns_id} Namespace id from |nvim_create_namespace()| or -1 for all
namespaces
• {start} Start of range: a 0-indexed (row, col) or valid extmark id
@@ -2849,7 +2850,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
Since: 0.5.0
Parameters: ~
- • {buffer} Buffer handle, or 0 for current buffer
+ • {buffer} Buffer id, or 0 for current buffer
• {ns_id} Namespace id from |nvim_create_namespace()|
• {line} Line where to place the mark, 0-based. |api-indexing|
• {col} Column where to place the mark, 0-based. |api-indexing|
@@ -3140,7 +3141,7 @@ nvim_win_get_buf({window}) *nvim_win_get_buf()*
• {window} |window-ID|, or 0 for current window
Return: ~
- Buffer handle
+ Buffer id
nvim_win_get_cursor({window}) *nvim_win_get_cursor()*
Gets the (1,0)-indexed, buffer-relative cursor position for a given window
@@ -3268,7 +3269,7 @@ nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()*
Parameters: ~
• {window} |window-ID|, or 0 for current window
- • {buffer} Buffer handle
+ • {buffer} Buffer id
nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()*
Sets the (1,0)-indexed cursor position in the window. |api-indexing| This
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 3a579ab194..d5e7554cbe 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -743,6 +743,12 @@ InsertLeavePre Just before leaving Insert mode. Also when
*InsertLeave*
InsertLeave Just after leaving Insert mode. Also when
using CTRL-O |i_CTRL-O|. But not for |i_CTRL-C|.
+LspAttach See |LspAttach|
+LspDetach See |LspDetach|
+LspNotify See |LspNotify|
+LspProgress See |LspProgress|
+LspRequest See |LspRequest|
+LspTokenUpdate See |LspTokenUpdate|
*MenuPopup*
MenuPopup Just before showing the popup menu (under the
right mouse button). Useful for adjusting the
@@ -1128,9 +1134,8 @@ VimLeave Before exiting Vim, just after writing the
Not triggered if |v:dying| is 2 or more.
*VimLeavePre*
VimLeavePre Before exiting Vim, just before writing the
- .shada file. This is executed only once,
- if there is a match with the name of what
- happens to be the current buffer when exiting.
+ |shada| file. Executed only once, if the
+ pattern matches the current buffer on exit.
Mostly useful with a "*" pattern. >
:autocmd VimLeavePre * call CleanupStuff()
< Use |v:dying| to detect an abnormal exit.
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
index 5cb969a531..f58d845e30 100644
--- a/runtime/doc/intro.txt
+++ b/runtime/doc/intro.txt
@@ -451,7 +451,7 @@ CTRL-O in Insert mode you get a beep but you are still in Insert mode, type
>
FROM mode TO mode
Normal Visual Select Insert Replace Cmd-line Ex >
- Normal v V ^V *4 *1 R gR : / ? ! Q
+ Normal v V ^V *4 *1 R gR : / ? ! gQ
Visual *2 ^G c C -- : --
Select *5 ^O ^G *6 -- -- --
Insert <Esc> -- -- <Insert> -- --
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 3a2de6bc70..50b2559dac 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -65,26 +65,75 @@ Follow these steps to get LSP features:
5. (Optional) Configure keymaps and autocommands to use LSP features.
|lsp-attach|
- *lsp-config*
+==============================================================================
+DEFAULTS *lsp-defaults*
-Configurations for LSP clients is done via |vim.lsp.config()|.
+When the Nvim LSP client starts it enables diagnostics |vim.diagnostic| (see
+|vim.diagnostic.config()| to customize). It also sets various default options,
+listed below, if (1) the language server supports the functionality and (2)
+the options are empty or were set by the builtin runtime (ftplugin) files. The
+options are not restored when the LSP client is stopped or detached.
-When an LSP client starts, it resolves a configuration by merging
-configurations, in increasing priority, from the following:
+- 'omnifunc' is set to |vim.lsp.omnifunc()|, use |i_CTRL-X_CTRL-O| to trigger
+ completion.
+- 'tagfunc' is set to |vim.lsp.tagfunc()|. This enables features like
+ go-to-definition, |:tjump|, and keymaps like |CTRL-]|, |CTRL-W_]|,
+ |CTRL-W_}| to utilize the language server.
+- 'formatexpr' is set to |vim.lsp.formatexpr()|, so you can format lines via
+ |gq| if the language server supports it.
+ - To opt out of this use |gw| instead of gq, or clear 'formatexpr' on |LspAttach|.
+- |K| is mapped to |vim.lsp.buf.hover()| unless |'keywordprg'| is customized or
+ a custom keymap for `K` exists.
-1. Configuration defined for the `'*'` name.
+ *grr* *gra* *grn* *gri* *i_CTRL-S*
+Some keymaps are created unconditionally when Nvim starts:
+- "grn" is mapped in Normal mode to |vim.lsp.buf.rename()|
+- "gra" is mapped in Normal and Visual mode to |vim.lsp.buf.code_action()|
+- "grr" is mapped in Normal mode to |vim.lsp.buf.references()|
+- "gri" is mapped in Normal mode to |vim.lsp.buf.implementation()|
+- "gO" is mapped in Normal mode to |vim.lsp.buf.document_symbol()|
+- CTRL-S is mapped in Insert mode to |vim.lsp.buf.signature_help()|
+If not wanted, these keymaps can be removed at any time using
+|vim.keymap.del()| or |:unmap| (see also |gr-default|).
+
+ *lsp-defaults-disable*
+To override or delete any of the above defaults, set or unset the options on
+|LspAttach|: >lua
+
+ vim.api.nvim_create_autocmd('LspAttach', {
+ callback = function(args)
+ -- Unset 'formatexpr'
+ vim.bo[args.buf].formatexpr = nil
+ -- Unset 'omnifunc'
+ vim.bo[args.buf].omnifunc = nil
+ -- Unmap K
+ vim.keymap.del('n', 'K', { buffer = args.buf })
+ end,
+ })
+<
+==============================================================================
+CONFIG *lsp-config*
+
+You can configure LSP behavior statically via vim.lsp.config(), and
+dynamically via |lsp-attach| or |Client:on_attach()|.
+
+Use |vim.lsp.config()| to define, and selectively enable, LSP configurations.
+This is basically a wrapper around |vim.lsp.start()| which allows you to share
+and merge configs (which may be provided by Nvim or third-party plugins).
+
+When an LSP client starts, it resolves its configuration by merging from the
+following (in increasing priority):
+
+1. Configuration defined for the `'*'` name.
2. Configuration from the result of merging all tables returned by
`lsp/<name>.lua` files in 'runtimepath' for a server of name `name`.
-
3. Configurations defined anywhere else.
Note: The merge semantics of configurations follow the behaviour of
|vim.tbl_deep_extend()|.
-Example:
-
-Given: >lua
+Example: given the following configs... >lua
-- Defined in init.lua
vim.lsp.config('*', {
capabilities = {
@@ -97,7 +146,7 @@ Given: >lua
root_markers = { '.git' },
})
- -- Defined in ../lsp/clangd.lua
+ -- Defined in <rtp>/lsp/clangd.lua
return {
cmd = { 'clangd' },
root_markers = { '.clangd', 'compile_commands.json' },
@@ -109,20 +158,20 @@ Given: >lua
filetypes = { 'c' },
})
<
-Results in the configuration: >lua
+...the merged result is: >lua
{
-- From the clangd configuration in <rtp>/lsp/clangd.lua
cmd = { 'clangd' },
-- From the clangd configuration in <rtp>/lsp/clangd.lua
- -- Overrides the * configuration in init.lua
+ -- Overrides the "*" configuration in init.lua
root_markers = { '.clangd', 'compile_commands.json' },
-- From the clangd configuration in init.lua
-- Overrides the clangd configuration in <rtp>/lsp/clangd.lua
filetypes = { 'c' },
- -- From the * configuration in init.lua
+ -- From the "*" configuration in init.lua
capabilities = {
textDocument = {
semanticTokens = {
@@ -132,71 +181,26 @@ Results in the configuration: >lua
}
}
<
- *lsp-defaults*
-When the Nvim LSP client starts it enables diagnostics |vim.diagnostic| (see
-|vim.diagnostic.config()| to customize). It also sets various default options,
-listed below, if (1) the language server supports the functionality and (2)
-the options are empty or were set by the builtin runtime (ftplugin) files. The
-options are not restored when the LSP client is stopped or detached.
-
-- 'omnifunc' is set to |vim.lsp.omnifunc()|, use |i_CTRL-X_CTRL-O| to trigger
- completion.
-- 'tagfunc' is set to |vim.lsp.tagfunc()|. This enables features like
- go-to-definition, |:tjump|, and keymaps like |CTRL-]|, |CTRL-W_]|,
- |CTRL-W_}| to utilize the language server.
-- 'formatexpr' is set to |vim.lsp.formatexpr()|, so you can format lines via
- |gq| if the language server supports it.
- - To opt out of this use |gw| instead of gq, or clear 'formatexpr' on |LspAttach|.
-- |K| is mapped to |vim.lsp.buf.hover()| unless |'keywordprg'| is customized or
- a custom keymap for `K` exists.
-
- *grr* *gra* *grn* *gri* *i_CTRL-S*
-Some keymaps are created unconditionally when Nvim starts:
-- "grn" is mapped in Normal mode to |vim.lsp.buf.rename()|
-- "gra" is mapped in Normal and Visual mode to |vim.lsp.buf.code_action()|
-- "grr" is mapped in Normal mode to |vim.lsp.buf.references()|
-- "gri" is mapped in Normal mode to |vim.lsp.buf.implementation()|
-- "gO" is mapped in Normal mode to |vim.lsp.buf.document_symbol()|
-- CTRL-S is mapped in Insert mode to |vim.lsp.buf.signature_help()|
-
-If not wanted, these keymaps can be removed at any time using
-|vim.keymap.del()| or |:unmap| (see also |gr-default|).
-
- *lsp-defaults-disable*
-To override or delete any of the above defaults, set or unset the options on
-|LspAttach|: >lua
-
- vim.api.nvim_create_autocmd('LspAttach', {
- callback = function(args)
- -- Unset 'formatexpr'
- vim.bo[args.buf].formatexpr = nil
- -- Unset 'omnifunc'
- vim.bo[args.buf].omnifunc = nil
- -- Unmap K
- vim.keymap.del('n', 'K', { buffer = args.buf })
- end,
- })
-<
*lsp-attach*
-To use other LSP features, set keymaps and other buffer options on
-|LspAttach|. Not all language servers provide the same capabilities. Use
-capability checks to ensure you only use features supported by the language
-server. Example: >lua
+To use LSP features beyond those provided by Nvim (see |lsp-buf|), you can set
+keymaps and options on |Client:on_attach()| or |LspAttach|. Not all language
+servers provide the same capabilities; check `supports_method()` in your
+LspAttach handler. Example: >lua
vim.api.nvim_create_autocmd('LspAttach', {
callback = function(args)
local client = vim.lsp.get_client_by_id(args.data.client_id)
if client:supports_method('textDocument/implementation') then
- -- Create a keymap for vim.lsp.buf.implementation
+ -- Create a keymap for vim.lsp.buf.implementation ...
end
+ -- Enable auto-completion.
if client:supports_method('textDocument/completion') then
- -- Enable auto-completion
vim.lsp.completion.enable(true, client.id, args.buf, {autotrigger = true})
end
+ -- Format the current buffer on save.
if client:supports_method('textDocument/formatting') then
- -- Format the current buffer on save
vim.api.nvim_create_autocmd('BufWritePre', {
buffer = args.buf,
callback = function()
@@ -207,13 +211,10 @@ server. Example: >lua
end,
})
<
-To learn what capabilities are available you can run the following command in
-a buffer with a started LSP client: >vim
+To see the capabilities for a given server, try this in a LSP-enabled buffer: >vim
:lua =vim.lsp.get_clients()[1].server_capabilities
-Full list of features provided by default can be found in |lsp-buf|.
-
================================================================================
FAQ *lsp-faq*
@@ -537,14 +538,31 @@ the exact definition):
EVENTS *lsp-events*
LspAttach *LspAttach*
- After an LSP client attaches to a buffer. The |autocmd-pattern| is the
- name of the buffer. When used from Lua, the client ID is passed to the
- callback in the "data" table. See |lsp-attach| for an example.
+ After an LSP client performs "initialize" and attaches to a buffer. The
+ |autocmd-pattern| is the buffer name. The client ID is passed in the
+ Lua handler |event-data| argument.
+
+ Note: If the LSP server performs dynamic registration, capabilities may be
+ registered any time _after_ LspAttach. In that case you may want to handle
+ the "registerCapability" event. Example: >lua
+
+ vim.lsp.handlers['client/registerCapability'] = (function(overridden)
+ return function(err, res, ctx)
+ local result = overridden(err, res, ctx)
+ local client = vim.lsp.get_client_by_id(ctx.client_id)
+ if not client then
+ return
+ end
+ -- Call your custom on_attach logic...
+ -- my_on_attach(client, vim.api.nvim_get_current_buf())
+ return result
+ end
+ end)(vim.lsp.handlers['client/registerCapability'])
LspDetach *LspDetach*
- Just before an LSP client detaches from a buffer. The |autocmd-pattern|
- is the name of the buffer. When used from Lua, the client ID is passed
- to the callback in the "data" table. Example: >lua
+ Just before an LSP client detaches from a buffer. The |autocmd-pattern| is
+ the buffer name. The client ID is passed in the Lua handler |event-data|
+ argument. Example: >lua
vim.api.nvim_create_autocmd('LspDetach', {
callback = function(args)
@@ -566,8 +584,8 @@ LspNotify *LspNotify*
This event is triggered after each successful notification sent to an
LSP server.
- When used from Lua, the client_id, LSP method, and parameters are sent
- in the "data" table. Example: >lua
+ The client_id, LSP method, and parameters are sent in the Lua handler
+ |event-data| table argument. Example: >lua
vim.api.nvim_create_autocmd('LspNotify', {
callback = function(args)
@@ -592,9 +610,9 @@ LspProgress *LspProgress*
If the server sends a "work done progress", the `pattern` is set to `kind`
(one of `begin`, `report` or `end`).
- When used from Lua, the event contains a `data` table with `client_id` and
- `params` properties. `params` will contain the request params sent by the
- server (see `lsp.ProgressParams`).
+ The Lua handler |event-data| argument has `client_id` and `params`
+ properties, where `params` is the request params sent by the server (see
+ `lsp.ProgressParams`).
Example: >vim
autocmd LspProgress * redrawstatus
@@ -611,11 +629,10 @@ LspRequest *LspRequest*
is requested using `client.cancel_request(request_id)`, then this event
will trigger with {type} == `cancel`.
- When used from Lua, the client ID, request ID, and request are sent in
- the "data" table. See {requests} in |vim.lsp.Client| for details on the
- {request} value. If the request type is `complete`, the request will be
- deleted from the client's pending requests table immediately after
- calling the event's callbacks. Example: >lua
+ The Lua handler |event-data| argument has the client ID, request ID, and
+ request (described at |vim.lsp.Client|, {requests} field). If the request
+ type is `complete`, the request will be deleted from the client's pending
+ requests table after processing the event handlers. Example: >lua
vim.api.nvim_create_autocmd('LspRequest', {
callback = function(args)
@@ -641,11 +658,9 @@ LspRequest *LspRequest*
LspTokenUpdate *LspTokenUpdate*
When a visible semantic token is sent or updated by the LSP server, or
when an existing token becomes visible for the first time. The
- |autocmd-pattern| is the name of the buffer. When used from Lua, the
- token and client ID are passed to the callback in the "data" table. The
- token fields are documented in |vim.lsp.semantic_tokens.get_at_pos()|.
- Example:
- >lua
+ |autocmd-pattern| is the buffer name. The Lua handler |event-data|
+ argument has the client ID and token (see
+ |vim.lsp.semantic_tokens.get_at_pos()|). Example: >lua
vim.api.nvim_create_autocmd('LspTokenUpdate', {
callback = function(args)
@@ -1842,6 +1857,8 @@ activate "auto-completion" when you type any of the server-defined
`triggerCharacters`.
Example: activate LSP-driven auto-completion: >lua
+ -- Works best with completeopt=noselect.
+ vim.cmd[[set completeopt+=menuone,noselect,popup]]
vim.lsp.start({
name = 'ts_ls',
cmd = …,
diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt
index 48fa723800..52838d0cc7 100644
--- a/runtime/doc/motion.txt
+++ b/runtime/doc/motion.txt
@@ -852,7 +852,7 @@ unrelated.
'a - 'z lowercase marks, valid within one file
'A - 'Z uppercase marks, also called file marks, valid between files
-'0 - '9 numbered marks, set from .shada file
+'0 - '9 numbered marks, set from |shada| file
Lowercase marks 'a to 'z are remembered as long as the file remains in the
buffer list. If you remove the file from the buffer list, all its marks are
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 7aca0268c6..01d5efee4a 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -2349,12 +2349,13 @@ A jump table for the options with a short description can be found at |Q_op|.
when 'autoindent' is on. To insert a real tab when 'expandtab' is
on, use CTRL-V<Tab>. See also |:retab| and |ins-expandtab|.
- *'exrc'* *'ex'* *'noexrc'* *'noex'*
+ *'exrc'* *'ex'* *'noexrc'* *'noex'* *project-config* *workspace-config*
'exrc' 'ex' boolean (default off)
global
- Automatically execute .nvim.lua, .nvimrc, and .exrc files in the
- current directory, if the file is in the |trust| list. Use |:trust| to
- manage trusted files. See also |vim.secure.read()|.
+ Enables project-local configuration. Nvim will execute any .nvim.lua,
+ .nvimrc, or .exrc file found in the |current-directory|, if the file is
+ in the |trust| list. Use |:trust| to manage trusted files. See also
+ |vim.secure.read()|.
Compare 'exrc' to |editorconfig|:
- 'exrc' can execute any code; editorconfig only specifies settings.
diff --git a/runtime/doc/quickref.txt b/runtime/doc/quickref.txt
index 86147cfc2b..163f74da22 100644
--- a/runtime/doc/quickref.txt
+++ b/runtime/doc/quickref.txt
@@ -842,7 +842,7 @@ Short explanation of each option: *option-list*
'selection' 'sel' what type of selection to use
'selectmode' 'slm' when to use Select mode instead of Visual mode
'sessionoptions' 'ssop' options for |:mksession|
-'shada' 'sd' use .shada file upon startup and exiting
+'shada' 'sd' use |shada| file upon startup and exiting
'shell' 'sh' name of shell to use for external commands
'shellcmdflag' 'shcf' flag to shell to execute one command
'shellpipe' 'sp' string to put output of ":make" in error file
diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
index ea8a1c2565..618510fc4f 100644
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -198,21 +198,19 @@ doesn't interfere).
- fish: https://fishshell.com/docs/current/relnotes.html#improved-terminal-support
- kitty: https://sw.kovidgoyal.net/kitty/shell-integration/
+- powershell: https://learn.microsoft.com/en-us/windows/terminal/tutorials/shell-integration#powershell-pwshexe
- vscode: https://code.visualstudio.com/docs/terminal/shell-integration
-To configure bash to mark the start/end of each prompt, set $PROMPT_COMMAND
-and $PS1 as follows: >bash
+To configure bash to mark the start of each prompt, set $PROMPT_COMMAND: >bash
# Prompt start:
PROMPT_COMMAND='printf "\033]133;A\007"'
- # Prompt end:
- PS1="$PS1"'\033]133;B\007'
<
*terminal_]]* *terminal_[[*
The |]]| and |[[| motions jump to the next/previous prompts, if your shell
emits OSC 133 as described above.
- *terminal-shell-prompt-signs*
+ *shell-prompt-signs*
To annotate each terminal prompt with a sign, call |nvim_buf_set_extmark()|
from a |TermRequest| handler: >lua
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index 31335b4fbb..bb4e2dbec5 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -272,9 +272,9 @@ Grid Events (line-based) *ui-linegrid*
Activated by the `ext_linegrid` |ui-option|. Recommended for all new UIs.
Deactivates |ui-grid-old| implicitly.
-The biggest change compared to |ui-grid-old| is to use a single `grid_line`
-event to update the contents of a screen line (whereas the old protocol used
-a combination of cursor, highlight and text events)
+Unlike |ui-grid-old|, this UI extension emits a single `grid_line` event to
+update a screen-line (whereas the old protocol emitted separate cursor,
+highlight and text events per screen-line).
Most of these events take a `grid` index as first parameter. Grid 1 is the
global grid used by default for the entire editor screen state. The
@@ -351,8 +351,7 @@ numerical highlight ids to the actual attributes.
affected by redefined ids, so UIs do not need to keep track of this
themselves.
- `info` is an empty array by default, and will be used by the
- |ui-hlstate| extension explained below.
+ `info` is an empty array unless |ui-hlstate| is enabled.
["hl_group_set", name, hl_id] ~
The built-in highlight group `name` was set to use the attributes `hl_id`
@@ -540,20 +539,23 @@ is not active. New UIs should implement |ui-linegrid| instead.
+-------------------------+
<
==============================================================================
-Detailed highlight state Extension *ui-hlstate*
+Highlight Events *ui-hlstate*
Activated by the `ext_hlstate` |ui-option|.
Activates |ui-linegrid| implicitly.
-By default Nvim will only describe grid cells using the final calculated
-highlight attributes, as described by the dict keys in |ui-event-highlight_set|.
-The `ext_hlstate` extension allows to the UI to also receive a semantic
-description of the highlights active in a cell. In this mode highlights will be
-predefined in a table, see |ui-event-hl_attr_define| and |ui-event-grid_line|.
-The `info` parameter in `hl_attr_define` will contain a semantic description
-of the highlights. As highlight groups can be combined, this will be an array
-of items, with the item with highest priority last. Each item is a dictionary
-with the following possible keys:
+If `ext_hlstate` is enabled, Nvim will emit detailed highlight state in
+|ui-linegrid| events. Otherwise (by default) Nvim only describes grid cells
+using the final calculated highlight attributes described at
+|ui-event-highlight_set|.
+
+`ext_hlstate` provides a semantic description of active highlights for each
+grid cell. Highlights are predefined in a table, see |ui-event-hl_attr_define|
+and |ui-event-grid_line|.
+
+The `info` parameter in `hl_attr_define` contains a semantic description of
+the highlights. Because highlight groups can be combined, this is an array
+where the highest-priority item is last. Each item is a dict with these keys:
`kind`: always present. One of the following values:
"ui": Builtin UI highlight. |highlight-groups|
@@ -671,6 +673,10 @@ Activated by the `ext_popupmenu` |ui-option|.
This UI extension delegates presentation of the |popupmenu-completion| and
command-line 'wildmenu'.
+The UI decides how to present the menu. For example, depending on the last
+`mode_change` event, command-line wildmenu may be presented horizontally,
+while insert-mode completion would show a vertical popupmenu.
+
["popupmenu_show", items, selected, row, col, grid] ~
Show |popupmenu-completion|. `items` is an array of completion items
to show; each item is an array of the form [word, kind, menu, info] as
diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt
index 848942a21f..18b09be3a2 100644
--- a/runtime/doc/vvars.txt
+++ b/runtime/doc/vvars.txt
@@ -153,45 +153,43 @@ v:event
an aborting condition (e.g. |c_Esc| or
|c_CTRL-C| for |CmdlineLeave|).
chan |channel-id|
- info Dict of arbitrary event data.
+ changed_window Is |v:true| if the event fired while
+ changing window (or tab) on |DirChanged|.
cmdlevel Level of cmdline.
cmdtype Type of cmdline, |cmdline-char|.
+ col Column count of popup menu on |CompleteChanged|,
+ relative to screen.
+ complete_type See |complete_info_mode|
+ complete_word The selected word, or empty if completion
+ was abandoned/discarded.
+ completed_item Current selected item on |CompleteChanged|,
+ or `{}` if no item selected.
cwd Current working directory.
+ height Height of popup menu on |CompleteChanged|
inclusive Motion is |inclusive|, else exclusive.
- scope Event-specific scope name.
+ info Dict of arbitrary event data.
operator Current |operator|. Also set for Ex
commands (unlike |v:operator|). For
example if |TextYankPost| is triggered
by the |:yank| Ex command then
`v:event.operator` is "y".
+ reason |CompleteDone| reason.
regcontents Text stored in the register as a
|readfile()|-style list of lines.
- regname Requested register (e.g "x" for "xyy)
- or the empty string for an unnamed
- operation.
+ regname Requested register (e.g "x" for "xyy), or
+ empty string for an unnamed operation.
regtype Type of register as returned by
|getregtype()|.
- visual Selection is visual (as opposed to,
- e.g., via motion).
- completed_item Current selected complete item on
- |CompleteChanged|, Is `{}` when no complete
- item selected.
- height Height of popup menu on |CompleteChanged|
- width Width of popup menu on |CompleteChanged|
row Row count of popup menu on |CompleteChanged|,
relative to screen.
- col Col count of popup menu on |CompleteChanged|,
- relative to screen.
+ scope Event-specific scope name.
+ scrollbar |v:true| if popup menu has a scrollbar, or
+ |v:false| if not.
size Total number of completion items on
|CompleteChanged|.
- scrollbar Is |v:true| if popup menu have scrollbar, or
- |v:false| if not.
- changed_window Is |v:true| if the event fired while
- changing window (or tab) on |DirChanged|.
status Job status or exit code, -1 means "unknown". |TermClose|
- reason Reason for completion being done. |CompleteDone|
- complete_word The word that was selected, empty if abandoned complete.
- complete_type See |complete_info_mode|
+ visual Selection is visual (as opposed to e.g. a motion range).
+ width Width of popup menu on |CompleteChanged|
windows List of window IDs that changed on |WinResized|
*v:exception* *exception-variable*
@@ -567,13 +565,19 @@ v:servername
*$NVIM*
$NVIM is set by |terminal| and |jobstart()|, and is thus
a hint that the current environment is a subprocess of Nvim.
- Example: >vim
- if $NVIM
- echo nvim_get_chan_info(v:parent)
- endif
-<
- Note the contents of $NVIM may change in the future.
+ Example: a child Nvim process can detect and make requests to
+ its parent Nvim: >lua
+
+ if vim.env.NVIM then
+ local ok, chan = pcall(vim.fn.sockconnect, 'pipe', vim.env.NVIM, {rpc=true})
+ if ok and chan then
+ local client = vim.api.nvim_get_chan_info(chan).client
+ local rv = vim.rpcrequest(chan, 'nvim_exec_lua', [[return ... + 1]], { 41 })
+ vim.print(('got "%s" from parent Nvim'):format(rv))
+ end
+ end
+<
*v:shell_error* *shell_error-variable*
v:shell_error
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 63a7bcc37d..ece3c1854b 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -176,7 +176,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
---
--- @see vim.api.nvim_buf_detach
--- @see `:help api-buffer-updates-lua`
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param send_buffer boolean True if the initial notification should contain the
--- whole buffer: first notification will be `nvim_buf_lines_event`.
--- Else the first notification will be `nvim_buf_changedtick_event`.
@@ -185,7 +185,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
--- - on_lines: Lua callback invoked on change.
--- Return a truthy value (not `false` or `nil`) to detach. Args:
--- - the string "lines"
---- - buffer handle
+--- - buffer id
--- - b:changedtick
--- - first line that changed (zero-indexed)
--- - last line that was changed
@@ -198,7 +198,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
--- change compared to on_lines.
--- Return a truthy value (not `false` or `nil`) to detach. Args:
--- - the string "bytes"
---- - buffer handle
+--- - buffer id
--- - b:changedtick
--- - start row of the changed text (zero-indexed)
--- - start column of the changed text
@@ -215,15 +215,15 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
--- - on_changedtick: Lua callback invoked on changedtick
--- increment without text change. Args:
--- - the string "changedtick"
---- - buffer handle
+--- - buffer id
--- - b:changedtick
--- - on_detach: Lua callback invoked on detach. Args:
--- - the string "detach"
---- - buffer handle
+--- - buffer id
--- - on_reload: Lua callback invoked on reload. The entire buffer
--- content should be considered changed. Args:
--- - the string "reload"
---- - buffer handle
+--- - buffer id
--- - utf_sizes: include UTF-32 and UTF-16 size of the replaced
--- region, as args to `on_lines`.
--- - preview: also attach to command preview (i.e. 'inccommand')
@@ -244,7 +244,7 @@ function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end
--- This is useful e.g. to call Vimscript functions that only work with the
--- current buffer/window currently, like `jobstart(…, {'term': v:true})`.
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param fun function Function to call inside the buffer (currently Lua callable
--- only)
--- @return any # Return value of function.
@@ -263,7 +263,7 @@ function vim.api.nvim_buf_clear_highlight(buffer, ns_id, line_start, line_end) e
--- Lines are 0-indexed. `api-indexing` To clear the namespace in the entire
--- buffer, specify line_start=0 and line_end=-1.
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param ns_id integer Namespace to clear, or -1 to clear all namespaces.
--- @param line_start integer Start of range of lines to clear
--- @param line_end integer End of range of lines to clear (exclusive) or -1 to clear
@@ -273,7 +273,7 @@ function vim.api.nvim_buf_clear_namespace(buffer, ns_id, line_start, line_end) e
--- Creates a buffer-local command `user-commands`.
---
--- @see vim.api.nvim_create_user_command
---- @param buffer integer Buffer handle, or 0 for current buffer.
+--- @param buffer integer Buffer id, or 0 for current buffer.
--- @param name string
--- @param command any
--- @param opts vim.api.keyset.user_command
@@ -281,7 +281,7 @@ function vim.api.nvim_buf_create_user_command(buffer, name, command, opts) end
--- Removes an `extmark`.
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param ns_id integer Namespace id from `nvim_create_namespace()`
--- @param id integer Extmark id
--- @return boolean # true if the extmark was found, else false
@@ -291,7 +291,7 @@ function vim.api.nvim_buf_del_extmark(buffer, ns_id, id) end
---
---
--- @see vim.api.nvim_del_keymap
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param mode string
--- @param lhs string
function vim.api.nvim_buf_del_keymap(buffer, mode, lhs) end
@@ -314,19 +314,19 @@ function vim.api.nvim_buf_del_mark(buffer, name) end
--- Only commands created with `:command-buffer` or
--- `nvim_buf_create_user_command()` can be deleted with this function.
---
---- @param buffer integer Buffer handle, or 0 for current buffer.
+--- @param buffer integer Buffer id, or 0 for current buffer.
--- @param name string Name of the command to delete.
function vim.api.nvim_buf_del_user_command(buffer, name) end
--- Removes a buffer-scoped (b:) variable
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param name string Variable name
function vim.api.nvim_buf_del_var(buffer, name) end
--- Deletes the buffer. See `:bwipeout`
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @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`
@@ -334,20 +334,20 @@ function vim.api.nvim_buf_delete(buffer, opts) end
--- Gets a changed tick of a buffer
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @return integer # `b:changedtick` value.
function vim.api.nvim_buf_get_changedtick(buffer) end
--- Gets a map of buffer-local `user-commands`.
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param opts vim.api.keyset.get_commands Optional parameters. Currently not used.
--- @return table<string,any> # Map of maps describing commands.
function vim.api.nvim_buf_get_commands(buffer, opts) end
--- Gets the position (0-indexed) of an `extmark`.
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param ns_id integer Namespace id from `nvim_create_namespace()`
--- @param id integer Extmark id
--- @param opts vim.api.keyset.get_extmark Optional parameters. Keys:
@@ -397,7 +397,7 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
--- vim.print(ms)
--- ```
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param ns_id integer Namespace id from `nvim_create_namespace()` or -1 for all namespaces
--- @param start any Start of range: a 0-indexed (row, col) or valid extmark id
--- (whose position defines the bound). `api-indexing`
@@ -415,10 +415,10 @@ function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end
--- Gets a list of buffer-local `mapping` definitions.
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param mode string Mode short-name ("n", "i", "v", ...)
--- @return vim.api.keyset.get_keymap[] # Array of |maparg()|-like dictionaries describing mappings.
---- The "buffer" key holds the associated buffer handle.
+--- The "buffer" key holds the associated buffer id.
function vim.api.nvim_buf_get_keymap(buffer, mode) end
--- Gets a line-range from the buffer.
@@ -430,7 +430,9 @@ function vim.api.nvim_buf_get_keymap(buffer, mode) end
--- Out-of-bounds indices are clamped to the nearest valid value, unless
--- `strict_indexing` is set.
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+---
+--- @see vim.api.nvim_buf_get_text
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param start integer First line index
--- @param end_ integer Last line index, exclusive
--- @param strict_indexing boolean Whether out-of-bounds should be an error.
@@ -445,7 +447,7 @@ function vim.api.nvim_buf_get_lines(buffer, start, end_, strict_indexing) end
---
--- @see vim.api.nvim_buf_set_mark
--- @see vim.api.nvim_buf_del_mark
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param name string Mark name
--- @return integer[] # (row, col) tuple, (0, 0) if the mark is not set, or is an
--- uppercase/file mark set in another buffer.
@@ -453,7 +455,7 @@ function vim.api.nvim_buf_get_mark(buffer, name) end
--- Gets the full file name for the buffer
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @return string # Buffer name
function vim.api.nvim_buf_get_name(buffer) end
@@ -472,7 +474,7 @@ function vim.api.nvim_buf_get_number(buffer) end
--- Unlike `line2byte()`, throws error for out-of-bounds indexing.
--- Returns -1 for unloaded buffer.
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param index integer Line index
--- @return integer # Integer byte offset, or -1 for unloaded buffer.
function vim.api.nvim_buf_get_offset(buffer, index) end
@@ -483,17 +485,14 @@ function vim.api.nvim_buf_get_offset(buffer, index) end
--- @return any
function vim.api.nvim_buf_get_option(buffer, name) end
---- Gets a range from the buffer.
----
---- This differs from `nvim_buf_get_lines()` in that it allows retrieving only
---- portions of a line.
+--- Gets a range from the buffer (may be partial lines, unlike `nvim_buf_get_lines()`).
---
--- Indexing is zero-based. Row indices are end-inclusive, and column indices
--- are end-exclusive.
---
--- Prefer `nvim_buf_get_lines()` when retrieving entire lines.
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param start_row integer First line index
--- @param start_col integer Starting column (byte offset) on first line
--- @param end_row integer Last line index, inclusive
@@ -504,7 +503,7 @@ function vim.api.nvim_buf_get_text(buffer, start_row, start_col, end_row, end_co
--- Gets a buffer-scoped (b:) variable.
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param name string Variable name
--- @return any # Variable value
function vim.api.nvim_buf_get_var(buffer, name) end
@@ -512,7 +511,7 @@ function vim.api.nvim_buf_get_var(buffer, name) end
--- Checks if a buffer is valid and loaded. See `api-buffer` for more info
--- about unloaded buffers.
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @return boolean # true if the buffer is valid and loaded, false otherwise.
function vim.api.nvim_buf_is_loaded(buffer) end
@@ -523,13 +522,13 @@ function vim.api.nvim_buf_is_loaded(buffer) end
--- for more info about unloaded buffers.
---
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @return boolean # true if the buffer is valid, false otherwise.
function vim.api.nvim_buf_is_valid(buffer) end
--- Returns the number of lines in the given buffer.
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @return integer # Line count, or 0 for unloaded buffer. |api-buffer|
function vim.api.nvim_buf_line_count(buffer) end
@@ -549,7 +548,7 @@ function vim.api.nvim_buf_line_count(buffer) end
--- An earlier end position is not an error, but then it behaves like an empty
--- range (no highlighting).
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param ns_id integer Namespace id from `nvim_create_namespace()`
--- @param line integer Line where to place the mark, 0-based. `api-indexing`
--- @param col integer Column where to place the mark, 0-based. `api-indexing`
@@ -685,7 +684,7 @@ function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end
---
---
--- @see vim.api.nvim_set_keymap
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param mode string
--- @param lhs string
--- @param rhs string
@@ -696,7 +695,7 @@ function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end
---
--- Indexing is zero-based, end-exclusive. Negative indices are interpreted
--- as length+1+index: -1 refers to the index past the end. So to change
---- or delete the last element use start=-2 and end=-1.
+--- or delete the last line use start=-2 and end=-1.
---
--- To insert lines at a given index, set `start` and `end` to the same index.
--- To delete a range of lines, set `replacement` to an empty array.
@@ -706,7 +705,7 @@ function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end
---
---
--- @see vim.api.nvim_buf_set_text
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param start integer First line index
--- @param end_ integer Last line index, exclusive
--- @param strict_indexing boolean Whether out-of-bounds should be an error.
@@ -734,7 +733,7 @@ function vim.api.nvim_buf_set_mark(buffer, name, line, col, opts) end
--- Sets the full file name for a buffer, like `:file_f`
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param name string Buffer name
function vim.api.nvim_buf_set_name(buffer, name) end
@@ -762,7 +761,7 @@ function vim.api.nvim_buf_set_option(buffer, name, value) end
--- Prefer |nvim_paste()| or |nvim_put()| to insert (instead of replace) text at cursor.
---
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param start_row integer First line index
--- @param start_col integer Starting column (byte offset) on first line
--- @param end_row integer Last line index, inclusive
@@ -772,7 +771,7 @@ function vim.api.nvim_buf_set_text(buffer, start_row, start_col, end_row, end_co
--- Sets a buffer-scoped (b:) variable
---
---- @param buffer integer Buffer handle, or 0 for current buffer
+--- @param buffer integer Buffer id, or 0 for current buffer
--- @param name string Variable name
--- @param value any Variable value
function vim.api.nvim_buf_set_var(buffer, name, value) end
@@ -964,7 +963,7 @@ function vim.api.nvim_create_autocmd(event, opts) end
--- @param listed boolean Sets 'buflisted'
--- @param scratch boolean Creates a "throwaway" `scratch-buffer` for temporary work
--- (always 'nomodified'). Also sets 'nomodeline' on the buffer.
---- @return integer # Buffer handle, or 0 on error
+--- @return integer # Buffer id, or 0 on error
---
function vim.api.nvim_create_buf(listed, scratch) end
@@ -1331,7 +1330,7 @@ function vim.api.nvim_get_context(opts) end
--- Gets the current buffer.
---
---- @return integer # Buffer handle
+--- @return integer # Buffer id
function vim.api.nvim_get_current_buf() end
--- Gets the current line.
@@ -1580,12 +1579,12 @@ function vim.api.nvim_input(keys) end
--- @param col integer Mouse column-position (zero-based, like redraw events)
function vim.api.nvim_input_mouse(button, action, modifier, grid, row, col) end
---- Gets the current list of buffer handles
+--- Gets the current list of buffers.
---
--- Includes unlisted (unloaded/deleted) buffers, like `:ls!`.
--- Use `nvim_buf_is_loaded()` to check if a buffer is loaded.
---
---- @return integer[] # List of buffer handles
+--- @return integer[] # List of buffer ids
function vim.api.nvim_list_bufs() end
--- Get information about all open channels.
@@ -1622,7 +1621,7 @@ function vim.api.nvim_list_tabpages() end
--- - "chan" |channel-id| of remote UI
function vim.api.nvim_list_uis() end
---- Gets the current list of window handles.
+--- Gets the current list of all `window-ID`s in all tabpages.
---
--- @return integer[] # List of |window-ID|s
function vim.api.nvim_list_wins() end
@@ -2069,7 +2068,7 @@ function vim.api.nvim_select_popupmenu_item(item, insert, finish, opts) end
--- Sets the current window's buffer to `buffer`.
---
---- @param buffer integer Buffer handle
+--- @param buffer integer Buffer id
function vim.api.nvim_set_current_buf(buffer) end
--- Changes the global working directory.
@@ -2087,7 +2086,7 @@ function vim.api.nvim_set_current_line(line) end
--- @param tabpage integer `tab-ID` to focus
function vim.api.nvim_set_current_tabpage(tabpage) end
---- Sets the current window. Also changes tabpage, if necessary.
+--- Sets the current window (and tabpage, implicitly).
---
--- @param window integer `window-ID` to focus
function vim.api.nvim_set_current_win(window) end
@@ -2361,7 +2360,7 @@ function vim.api.nvim_win_del_var(window, name) end
--- Gets the current buffer in a window
---
--- @param window integer `window-ID`, or 0 for current window
---- @return integer # Buffer handle
+--- @return integer # Buffer id
function vim.api.nvim_win_get_buf(window) end
--- Gets window configuration.
@@ -2446,7 +2445,7 @@ function vim.api.nvim_win_is_valid(window) end
--- Sets the current buffer in a window, without side effects
---
--- @param window integer `window-ID`, or 0 for current window
---- @param buffer integer Buffer handle
+--- @param buffer integer Buffer id
function vim.api.nvim_win_set_buf(window, buffer) end
--- Configures window layout. Cannot be used to move the last window in a
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 775dda59f7..5e138c1a4a 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -2010,9 +2010,10 @@ vim.o.et = vim.o.expandtab
vim.bo.expandtab = vim.o.expandtab
vim.bo.et = vim.bo.expandtab
---- Automatically execute .nvim.lua, .nvimrc, and .exrc files in the
---- current directory, if the file is in the `trust` list. Use `:trust` to
---- manage trusted files. See also `vim.secure.read()`.
+--- Enables project-local configuration. Nvim will execute any .nvim.lua,
+--- .nvimrc, or .exrc file found in the `current-directory`, if the file is
+--- in the `trust` list. Use `:trust` to manage trusted files. See also
+--- `vim.secure.read()`.
---
--- Compare 'exrc' to `editorconfig`:
--- - 'exrc' can execute any code; editorconfig only specifies settings.
diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
index a44ad6c7d9..9df5a0b5f2 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -160,45 +160,43 @@ vim.v.errors = ...
--- an aborting condition (e.g. `c_Esc` or
--- `c_CTRL-C` for `CmdlineLeave`).
--- chan `channel-id`
---- info Dict of arbitrary event data.
+--- changed_window Is `v:true` if the event fired while
+--- changing window (or tab) on `DirChanged`.
--- cmdlevel Level of cmdline.
--- cmdtype Type of cmdline, `cmdline-char`.
+--- col Column count of popup menu on `CompleteChanged`,
+--- relative to screen.
+--- complete_type See `complete_info_mode`
+--- complete_word The selected word, or empty if completion
+--- was abandoned/discarded.
+--- completed_item Current selected item on `CompleteChanged`,
+--- or `{}` if no item selected.
--- cwd Current working directory.
+--- height Height of popup menu on `CompleteChanged`
--- inclusive Motion is `inclusive`, else exclusive.
---- scope Event-specific scope name.
+--- info Dict of arbitrary event data.
--- operator Current `operator`. Also set for Ex
--- commands (unlike `v:operator`). For
--- example if `TextYankPost` is triggered
--- by the `:yank` Ex command then
--- `v:event.operator` is "y".
+--- reason `CompleteDone` reason.
--- regcontents Text stored in the register as a
--- `readfile()`-style list of lines.
---- regname Requested register (e.g "x" for "xyy)
---- or the empty string for an unnamed
---- operation.
+--- regname Requested register (e.g "x" for "xyy), or
+--- empty string for an unnamed operation.
--- regtype Type of register as returned by
--- `getregtype()`.
---- visual Selection is visual (as opposed to,
---- e.g., via motion).
---- completed_item Current selected complete item on
---- `CompleteChanged`, Is `{}` when no complete
---- item selected.
---- height Height of popup menu on `CompleteChanged`
---- width Width of popup menu on `CompleteChanged`
--- row Row count of popup menu on `CompleteChanged`,
--- relative to screen.
---- col Col count of popup menu on `CompleteChanged`,
---- relative to screen.
+--- scope Event-specific scope name.
+--- scrollbar `v:true` if popup menu has a scrollbar, or
+--- `v:false` if not.
--- size Total number of completion items on
--- `CompleteChanged`.
---- scrollbar Is `v:true` if popup menu have scrollbar, or
---- `v:false` if not.
---- changed_window Is `v:true` if the event fired while
---- changing window (or tab) on `DirChanged`.
--- status Job status or exit code, -1 means "unknown". `TermClose`
---- reason Reason for completion being done. `CompleteDone`
---- complete_word The word that was selected, empty if abandoned complete.
---- complete_type See `complete_info_mode`
+--- visual Selection is visual (as opposed to e.g. a motion range).
+--- width Width of popup menu on `CompleteChanged`
--- windows List of window IDs that changed on `WinResized`
--- @type vim.v.event
vim.v.event = ...
@@ -590,15 +588,21 @@ vim.v.searchforward = ...
--- *$NVIM*
--- $NVIM is set by `terminal` and `jobstart()`, and is thus
--- a hint that the current environment is a subprocess of Nvim.
---- Example:
---
---- ```vim
---- if $NVIM
---- echo nvim_get_chan_info(v:parent)
---- endif
---- ```
+--- Example: a child Nvim process can detect and make requests to
+--- its parent Nvim:
+---
+--- ```lua
---
---- Note the contents of $NVIM may change in the future.
+--- if vim.env.NVIM then
+--- local ok, chan = pcall(vim.fn.sockconnect, 'pipe', vim.env.NVIM, {rpc=true})
+--- if ok and chan then
+--- local client = vim.api.nvim_get_chan_info(chan).client
+--- local rv = vim.rpcrequest(chan, 'nvim_exec_lua', [[return ... + 1]], { 41 })
+--- vim.print(('got "%s" from parent Nvim'):format(rv))
+--- end
+--- end
+--- ```
--- @type string
vim.v.servername = ...
diff --git a/runtime/lua/vim/lsp/completion.lua b/runtime/lua/vim/lsp/completion.lua
index dcb7b5fa9b..6aedac8fd9 100644
--- a/runtime/lua/vim/lsp/completion.lua
+++ b/runtime/lua/vim/lsp/completion.lua
@@ -6,6 +6,8 @@
---
--- Example: activate LSP-driven auto-completion:
--- ```lua
+--- -- Works best with completeopt=noselect.
+--- vim.cmd[[set completeopt+=menuone,noselect,popup]]
--- vim.lsp.start({
--- name = 'ts_ls',
--- cmd = …,
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index aa349790b3..f8ebf4b838 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -67,7 +67,7 @@
/// Returns the number of lines in the given buffer.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param[out] err Error details, if any
/// @return Line count, or 0 for unloaded buffer. |api-buffer|
Integer nvim_buf_line_count(Buffer buffer, Error *err)
@@ -105,7 +105,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// @see |api-buffer-updates-lua|
///
/// @param channel_id
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param send_buffer True if the initial notification should contain the
/// whole buffer: first notification will be `nvim_buf_lines_event`.
/// Else the first notification will be `nvim_buf_changedtick_event`.
@@ -114,7 +114,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// - on_lines: Lua callback invoked on change.
/// Return a truthy value (not `false` or `nil`) to detach. Args:
/// - the string "lines"
-/// - buffer handle
+/// - buffer id
/// - b:changedtick
/// - first line that changed (zero-indexed)
/// - last line that was changed
@@ -127,7 +127,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// change compared to on_lines.
/// Return a truthy value (not `false` or `nil`) to detach. Args:
/// - the string "bytes"
-/// - buffer handle
+/// - buffer id
/// - b:changedtick
/// - start row of the changed text (zero-indexed)
/// - start column of the changed text
@@ -144,15 +144,15 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// - on_changedtick: Lua callback invoked on changedtick
/// increment without text change. Args:
/// - the string "changedtick"
-/// - buffer handle
+/// - buffer id
/// - b:changedtick
/// - on_detach: Lua callback invoked on detach. Args:
/// - the string "detach"
-/// - buffer handle
+/// - buffer id
/// - on_reload: Lua callback invoked on reload. The entire buffer
/// content should be considered changed. Args:
/// - the string "reload"
-/// - buffer handle
+/// - buffer id
/// - utf_sizes: include UTF-32 and UTF-16 size of the replaced
/// region, as args to `on_lines`.
/// - preview: also attach to command preview (i.e. 'inccommand')
@@ -212,7 +212,7 @@ Boolean nvim_buf_attach(uint64_t channel_id, Buffer buffer, Boolean send_buffer,
/// @see |api-lua-detach| for detaching Lua callbacks
///
/// @param channel_id
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param[out] err Error details, if any
/// @return False if detach failed (because the buffer isn't loaded);
/// otherwise True.
@@ -238,8 +238,10 @@ Boolean nvim_buf_detach(uint64_t channel_id, Buffer buffer, Error *err)
/// Out-of-bounds indices are clamped to the nearest valid value, unless
/// `strict_indexing` is set.
///
+/// @see |nvim_buf_get_text()|
+///
/// @param channel_id
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param start First line index
/// @param end Last line index, exclusive
/// @param strict_indexing Whether out-of-bounds should be an error.
@@ -294,7 +296,7 @@ ArrayOf(String) nvim_buf_get_lines(uint64_t channel_id,
///
/// Indexing is zero-based, end-exclusive. Negative indices are interpreted
/// as length+1+index: -1 refers to the index past the end. So to change
-/// or delete the last element use start=-2 and end=-1.
+/// or delete the last line use start=-2 and end=-1.
///
/// To insert lines at a given index, set `start` and `end` to the same index.
/// To delete a range of lines, set `replacement` to an empty array.
@@ -305,7 +307,7 @@ ArrayOf(String) nvim_buf_get_lines(uint64_t channel_id,
/// @see |nvim_buf_set_text()|
///
/// @param channel_id
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param start First line index
/// @param end Last line index, exclusive
/// @param strict_indexing Whether out-of-bounds should be an error.
@@ -463,7 +465,7 @@ void nvim_buf_set_lines(uint64_t channel_id, Buffer buffer, Integer start, Integ
/// @note Prefer |nvim_paste()| or |nvim_put()| to insert (instead of replace) text at cursor.
///
/// @param channel_id
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param start_row First line index
/// @param start_col Starting column (byte offset) on first line
/// @param end_row Last line index, inclusive
@@ -685,10 +687,7 @@ void nvim_buf_set_text(uint64_t channel_id, Buffer buffer, Integer start_row, In
});
}
-/// Gets a range from the buffer.
-///
-/// This differs from |nvim_buf_get_lines()| in that it allows retrieving only
-/// portions of a line.
+/// Gets a range from the buffer (may be partial lines, unlike |nvim_buf_get_lines()|).
///
/// Indexing is zero-based. Row indices are end-inclusive, and column indices
/// are end-exclusive.
@@ -696,7 +695,7 @@ void nvim_buf_set_text(uint64_t channel_id, Buffer buffer, Integer start_row, In
/// Prefer |nvim_buf_get_lines()| when retrieving entire lines.
///
/// @param channel_id
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param start_row First line index
/// @param start_col Starting column (byte offset) on first line
/// @param end_row Last line index, inclusive
@@ -790,7 +789,7 @@ end:
/// Unlike |line2byte()|, throws error for out-of-bounds indexing.
/// Returns -1 for unloaded buffer.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param index Line index
/// @param[out] err Error details, if any
/// @return Integer byte offset, or -1 for unloaded buffer.
@@ -816,7 +815,7 @@ Integer nvim_buf_get_offset(Buffer buffer, Integer index, Error *err)
/// Gets a buffer-scoped (b:) variable.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param name Variable name
/// @param[out] err Error details, if any
/// @return Variable value
@@ -834,7 +833,7 @@ Object nvim_buf_get_var(Buffer buffer, String name, Arena *arena, Error *err)
/// Gets a changed tick of a buffer
///
-/// @param[in] buffer Buffer handle, or 0 for current buffer
+/// @param[in] buffer Buffer id, or 0 for current buffer
/// @param[out] err Error details, if any
///
/// @return `b:changedtick` value.
@@ -852,11 +851,11 @@ Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
/// Gets a list of buffer-local |mapping| definitions.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param mode Mode short-name ("n", "i", "v", ...)
/// @param[out] err Error details, if any
/// @returns Array of |maparg()|-like dictionaries describing mappings.
-/// The "buffer" key holds the associated buffer handle.
+/// The "buffer" key holds the associated buffer id.
ArrayOf(Dict) nvim_buf_get_keymap(Buffer buffer, String mode, Arena *arena, Error *err)
FUNC_API_SINCE(3)
{
@@ -873,7 +872,7 @@ ArrayOf(Dict) nvim_buf_get_keymap(Buffer buffer, String mode, Arena *arena, Erro
///
/// @see |nvim_set_keymap()|
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
void nvim_buf_set_keymap(uint64_t channel_id, Buffer buffer, String mode, String lhs, String rhs,
Dict(keymap) *opts, Error *err)
FUNC_API_SINCE(6)
@@ -885,7 +884,7 @@ void nvim_buf_set_keymap(uint64_t channel_id, Buffer buffer, String mode, String
///
/// @see |nvim_del_keymap()|
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
void nvim_buf_del_keymap(uint64_t channel_id, Buffer buffer, String mode, String lhs, Error *err)
FUNC_API_SINCE(6)
{
@@ -895,7 +894,7 @@ void nvim_buf_del_keymap(uint64_t channel_id, Buffer buffer, String mode, String
/// Sets a buffer-scoped (b:) variable
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param name Variable name
/// @param value Variable value
/// @param[out] err Error details, if any
@@ -913,7 +912,7 @@ void nvim_buf_set_var(Buffer buffer, String name, Object value, Error *err)
/// Removes a buffer-scoped (b:) variable
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param name Variable name
/// @param[out] err Error details, if any
void nvim_buf_del_var(Buffer buffer, String name, Error *err)
@@ -930,7 +929,7 @@ void nvim_buf_del_var(Buffer buffer, String name, Error *err)
/// Gets the full file name for the buffer
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param[out] err Error details, if any
/// @return Buffer name
String nvim_buf_get_name(Buffer buffer, Error *err)
@@ -948,7 +947,7 @@ String nvim_buf_get_name(Buffer buffer, Error *err)
/// Sets the full file name for a buffer, like |:file_f|
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param name Buffer name
/// @param[out] err Error details, if any
void nvim_buf_set_name(Buffer buffer, String name, Error *err)
@@ -992,7 +991,7 @@ void nvim_buf_set_name(Buffer buffer, String name, Error *err)
/// Checks if a buffer is valid and loaded. See |api-buffer| for more info
/// about unloaded buffers.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @return true if the buffer is valid and loaded, false otherwise.
Boolean nvim_buf_is_loaded(Buffer buffer)
FUNC_API_SINCE(5)
@@ -1005,7 +1004,7 @@ Boolean nvim_buf_is_loaded(Buffer buffer)
/// Deletes the buffer. See |:bwipeout|
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @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|
@@ -1040,7 +1039,7 @@ void nvim_buf_delete(Buffer buffer, Dict(buf_delete) *opts, Error *err)
/// @note Even if a buffer is valid it may have been unloaded. See |api-buffer|
/// for more info about unloaded buffers.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @return true if the buffer is valid, false otherwise.
Boolean nvim_buf_is_valid(Buffer buffer)
FUNC_API_SINCE(1)
@@ -1131,7 +1130,7 @@ Boolean nvim_buf_set_mark(Buffer buffer, String name, Integer line, Integer col,
///
/// Marks are (1,0)-indexed. |api-indexing|
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param name Mark name
/// @param[out] err Error details, if any
/// @return (row, col) tuple, (0, 0) if the mark is not set, or is an
@@ -1187,7 +1186,7 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Arena *arena,
/// This is useful e.g. to call Vimscript functions that only work with the
/// current buffer/window currently, like `jobstart(…, {'term': v:true})`.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param fun Function to call inside the buffer (currently Lua callable
/// only)
/// @param[out] err Error details, if any
diff --git a/src/nvim/api/command.c b/src/nvim/api/command.c
index 23e08bd3fe..de83ff97f7 100644
--- a/src/nvim/api/command.c
+++ b/src/nvim/api/command.c
@@ -897,7 +897,7 @@ void nvim_del_user_command(String name, Error *err)
/// Creates a buffer-local command |user-commands|.
///
-/// @param buffer Buffer handle, or 0 for current buffer.
+/// @param buffer Buffer id, or 0 for current buffer.
/// @param[out] err Error details, if any.
/// @see nvim_create_user_command
void nvim_buf_create_user_command(uint64_t channel_id, Buffer buffer, String name, Object command,
@@ -920,7 +920,7 @@ void nvim_buf_create_user_command(uint64_t channel_id, Buffer buffer, String nam
/// Only commands created with |:command-buffer| or
/// |nvim_buf_create_user_command()| can be deleted with this function.
///
-/// @param buffer Buffer handle, or 0 for current buffer.
+/// @param buffer Buffer id, or 0 for current buffer.
/// @param name Name of the command to delete.
/// @param[out] err Error details, if any.
void nvim_buf_del_user_command(Buffer buffer, String name, Error *err)
@@ -1178,7 +1178,7 @@ Dict nvim_get_commands(Dict(get_commands) *opts, Arena *arena, Error *err)
/// Gets a map of buffer-local |user-commands|.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param opts Optional parameters. Currently not used.
/// @param[out] err Error details, if any.
///
diff --git a/src/nvim/api/deprecated.c b/src/nvim/api/deprecated.c
index 767a7a8bc8..cf2aebf274 100644
--- a/src/nvim/api/deprecated.c
+++ b/src/nvim/api/deprecated.c
@@ -69,7 +69,7 @@ Object nvim_execute_lua(String code, Array args, Arena *arena, Error *err)
///
/// @deprecated The buffer number now is equal to the object id
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param[out] err Error details, if any
/// @return Buffer number
Integer nvim_buf_get_number(Buffer buffer, Error *err)
@@ -100,7 +100,7 @@ static uint32_t src2ns(Integer *src_id)
///
/// @deprecated use |nvim_buf_clear_namespace()|.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param ns_id Namespace to clear, or -1 to clear all.
/// @param line_start Start of range of lines to clear
/// @param line_end End of range of lines to clear (exclusive) or -1 to clear
@@ -131,7 +131,7 @@ void nvim_buf_clear_highlight(Buffer buffer, Integer ns_id, Integer line_start,
/// supported for backwards compatibility, new code should use
/// |nvim_create_namespace()| to create a new empty namespace.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param ns_id namespace to use or -1 for ungrouped highlight
/// @param hl_group Name of the highlight group to use
/// @param line Line to highlight (zero-indexed)
@@ -207,7 +207,7 @@ Integer nvim_buf_add_highlight(Buffer buffer, Integer ns_id, String hl_group, In
/// As a shorthand, `ns_id = 0` can be used to create a new namespace for the
/// virtual text, the allocated id is then returned.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param src_id Namespace to use or 0 to create a namespace,
/// or -1 for a ungrouped annotation
/// @param line Line to annotate with virtual text (zero-indexed)
@@ -309,7 +309,7 @@ Dict nvim_get_hl_by_name(String name, Boolean rgb, Arena *arena, Error *err)
///
/// @deprecated use nvim_buf_set_lines(buffer, lnum, lnum, true, lines)
///
-/// @param buffer Buffer handle
+/// @param buffer Buffer id
/// @param lnum Insert the lines after `lnum`. If negative, appends to
/// the end of the buffer.
/// @param lines Array of lines
@@ -330,7 +330,7 @@ void buffer_insert(Buffer buffer, Integer lnum, ArrayOf(String) lines, Arena *ar
/// for negative indices use
/// "nvim_buf_get_lines(buffer, index-1, index, true)"
///
-/// @param buffer Buffer handle
+/// @param buffer Buffer id
/// @param index Line index
/// @param[out] err Error details, if any
/// @return Line string
@@ -357,7 +357,7 @@ String buffer_get_line(Buffer buffer, Integer index, Arena *arena, Error *err)
/// for negative indices use
/// "nvim_buf_set_lines(buffer, index-1, index, true, [line])"
///
-/// @param buffer Buffer handle
+/// @param buffer Buffer id
/// @param index Line index
/// @param line Contents of the new line
/// @param[out] err Error details, if any
@@ -377,7 +377,7 @@ void buffer_set_line(Buffer buffer, Integer index, String line, Arena *arena, Er
/// "nvim_buf_set_lines(buffer, index, index+1, true, [])"
/// for negative indices use
/// "nvim_buf_set_lines(buffer, index-1, index, true, [])"
-/// @param buffer buffer handle
+/// @param buffer buffer id
/// @param index line index
/// @param[out] err Error details, if any
void buffer_del_line(Buffer buffer, Integer index, Arena *arena, Error *err)
@@ -394,7 +394,7 @@ void buffer_del_line(Buffer buffer, Integer index, Arena *arena, Error *err)
/// where newstart = start + int(not include_start) - int(start < 0)
/// newend = end + int(include_end) - int(end < 0)
/// int(bool) = 1 if bool is true else 0
-/// @param buffer Buffer handle
+/// @param buffer Buffer id
/// @param start First line index
/// @param end Last line index
/// @param include_start True if the slice includes the `start` parameter
@@ -422,7 +422,7 @@ ArrayOf(String) buffer_get_line_slice(Buffer buffer,
/// newend = end + int(include_end) + int(end < 0)
/// int(bool) = 1 if bool is true else 0
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param start First line index
/// @param end Last line index
/// @param include_start True if the slice includes the `start` parameter
@@ -444,7 +444,7 @@ void buffer_set_line_slice(Buffer buffer, Integer start, Integer end, Boolean in
///
/// @deprecated
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param name Variable name
/// @param value Variable value
/// @param[out] err Error details, if any
@@ -468,7 +468,7 @@ Object buffer_set_var(Buffer buffer, String name, Object value, Arena *arena, Er
///
/// @deprecated
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param name Variable name
/// @param[out] err Error details, if any
/// @return Old value
@@ -641,7 +641,7 @@ Object nvim_get_option(String name, Error *err)
/// Gets a buffer option value
///
/// @deprecated
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param name Option name
/// @param[out] err Error details, if any
/// @return Option value
@@ -664,7 +664,7 @@ Object nvim_buf_get_option(Buffer buffer, String name, Error *err)
///
/// @deprecated
/// @param channel_id
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param name Option name
/// @param value Option value
/// @param[out] err Error details, if any
diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c
index 5420816726..95f2167c03 100644
--- a/src/nvim/api/extmark.c
+++ b/src/nvim/api/extmark.c
@@ -192,7 +192,7 @@ static Array extmark_to_array(MTPair extmark, bool id, bool add_dict, bool hl_na
/// Gets the position (0-indexed) of an |extmark|.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param ns_id Namespace id from |nvim_create_namespace()|
/// @param id Extmark id
/// @param opts Optional parameters. Keys:
@@ -269,7 +269,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
/// vim.print(ms)
/// ```
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param ns_id Namespace id from |nvim_create_namespace()| or -1 for all namespaces
/// @param start Start of range: a 0-indexed (row, col) or valid extmark id
/// (whose position defines the bound). |api-indexing|
@@ -374,7 +374,7 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e
/// An earlier end position is not an error, but then it behaves like an empty
/// range (no highlighting).
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param ns_id Namespace id from |nvim_create_namespace()|
/// @param line Line where to place the mark, 0-based. |api-indexing|
/// @param col Column where to place the mark, 0-based. |api-indexing|
@@ -922,7 +922,7 @@ error:
/// Removes an |extmark|.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param ns_id Namespace id from |nvim_create_namespace()|
/// @param id Extmark id
/// @param[out] err Error details, if any
@@ -948,7 +948,7 @@ Boolean nvim_buf_del_extmark(Buffer buffer, Integer ns_id, Integer id, Error *er
/// Lines are 0-indexed. |api-indexing| To clear the namespace in the entire
/// buffer, specify line_start=0 and line_end=-1.
///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
/// @param ns_id Namespace to clear, or -1 to clear all namespaces.
/// @param line_start Start of range of lines to clear
/// @param line_end End of range of lines to clear (exclusive) or -1 to clear
diff --git a/src/nvim/api/private/helpers.c b/src/nvim/api/private/helpers.c
index eca442845d..e303a23ee5 100644
--- a/src/nvim/api/private/helpers.c
+++ b/src/nvim/api/private/helpers.c
@@ -472,7 +472,7 @@ int64_t normalize_index(buf_T *buf, int64_t index, bool end_exclusive, bool *oob
/// Returns a substring of a buffer line
///
-/// @param buf Buffer handle
+/// @param buf Buffer id
/// @param lnum Line number (1-based)
/// @param start_col Starting byte offset into line (0-based)
/// @param end_col Ending byte offset into line (0-based, exclusive)
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index c734e2aa2a..70f5ebacb7 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -790,12 +790,12 @@ error:
hl_msg_free(hl_msg);
}
-/// Gets the current list of buffer handles
+/// Gets the current list of buffers.
///
/// Includes unlisted (unloaded/deleted) buffers, like `:ls!`.
/// Use |nvim_buf_is_loaded()| to check if a buffer is loaded.
///
-/// @return List of buffer handles
+/// @return List of buffer ids
ArrayOf(Buffer) nvim_list_bufs(Arena *arena)
FUNC_API_SINCE(1)
{
@@ -816,7 +816,7 @@ ArrayOf(Buffer) nvim_list_bufs(Arena *arena)
/// Gets the current buffer.
///
-/// @return Buffer handle
+/// @return Buffer id
Buffer nvim_get_current_buf(void)
FUNC_API_SINCE(1)
{
@@ -825,7 +825,7 @@ Buffer nvim_get_current_buf(void)
/// Sets the current window's buffer to `buffer`.
///
-/// @param buffer Buffer handle
+/// @param buffer Buffer id
/// @param[out] err Error details, if any
void nvim_set_current_buf(Buffer buffer, Error *err)
FUNC_API_SINCE(1)
@@ -842,7 +842,7 @@ void nvim_set_current_buf(Buffer buffer, Error *err)
});
}
-/// Gets the current list of window handles.
+/// Gets the current list of all |window-ID|s in all tabpages.
///
/// @return List of |window-ID|s
ArrayOf(Window) nvim_list_wins(Arena *arena)
@@ -872,7 +872,7 @@ Window nvim_get_current_win(void)
return curwin->handle;
}
-/// Sets the current window. Also changes tabpage, if necessary.
+/// Sets the current window (and tabpage, implicitly).
///
/// @param window |window-ID| to focus
/// @param[out] err Error details, if any
@@ -897,7 +897,7 @@ void nvim_set_current_win(Window window, Error *err)
/// @param scratch Creates a "throwaway" |scratch-buffer| for temporary work
/// (always 'nomodified'). Also sets 'nomodeline' on the buffer.
/// @param[out] err Error details, if any
-/// @return Buffer handle, or 0 on error
+/// @return Buffer id, or 0 on error
///
/// @see buf_open_scratch
Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
index c902a6effb..cde629dab3 100644
--- a/src/nvim/api/window.c
+++ b/src/nvim/api/window.c
@@ -34,7 +34,7 @@
///
/// @param window |window-ID|, or 0 for current window
/// @param[out] err Error details, if any
-/// @return Buffer handle
+/// @return Buffer id
Buffer nvim_win_get_buf(Window window, Error *err)
FUNC_API_SINCE(1)
{
@@ -50,7 +50,7 @@ Buffer nvim_win_get_buf(Window window, Error *err)
/// Sets the current buffer in a window, without side effects
///
/// @param window |window-ID|, or 0 for current window
-/// @param buffer Buffer handle
+/// @param buffer Buffer id
/// @param[out] err Error details, if any
void nvim_win_set_buf(Window window, Buffer buffer, Error *err)
FUNC_API_SINCE(5)
diff --git a/src/nvim/options.lua b/src/nvim/options.lua
index e9f8051ed3..d150303033 100644
--- a/src/nvim/options.lua
+++ b/src/nvim/options.lua
@@ -2663,9 +2663,10 @@ local options = {
abbreviation = 'ex',
defaults = false,
desc = [=[
- Automatically execute .nvim.lua, .nvimrc, and .exrc files in the
- current directory, if the file is in the |trust| list. Use |:trust| to
- manage trusted files. See also |vim.secure.read()|.
+ Enables project-local configuration. Nvim will execute any .nvim.lua,
+ .nvimrc, or .exrc file found in the |current-directory|, if the file is
+ in the |trust| list. Use |:trust| to manage trusted files. See also
+ |vim.secure.read()|.
Compare 'exrc' to |editorconfig|:
- 'exrc' can execute any code; editorconfig only specifies settings.
@@ -2678,6 +2679,7 @@ local options = {
scope = { 'global' },
secure = true,
short_desc = N_('read .nvimrc and .exrc in the current directory'),
+ tags = { 'project-config', 'workspace-config' },
type = 'boolean',
varname = 'p_exrc',
},
diff --git a/src/nvim/vvars.lua b/src/nvim/vvars.lua
index 52af56e607..cb84df015c 100644
--- a/src/nvim/vvars.lua
+++ b/src/nvim/vvars.lua
@@ -175,45 +175,43 @@ M.vars = {
an aborting condition (e.g. |c_Esc| or
|c_CTRL-C| for |CmdlineLeave|).
chan |channel-id|
- info Dict of arbitrary event data.
+ changed_window Is |v:true| if the event fired while
+ changing window (or tab) on |DirChanged|.
cmdlevel Level of cmdline.
cmdtype Type of cmdline, |cmdline-char|.
+ col Column count of popup menu on |CompleteChanged|,
+ relative to screen.
+ complete_type See |complete_info_mode|
+ complete_word The selected word, or empty if completion
+ was abandoned/discarded.
+ completed_item Current selected item on |CompleteChanged|,
+ or `{}` if no item selected.
cwd Current working directory.
+ height Height of popup menu on |CompleteChanged|
inclusive Motion is |inclusive|, else exclusive.
- scope Event-specific scope name.
+ info Dict of arbitrary event data.
operator Current |operator|. Also set for Ex
commands (unlike |v:operator|). For
example if |TextYankPost| is triggered
by the |:yank| Ex command then
`v:event.operator` is "y".
+ reason |CompleteDone| reason.
regcontents Text stored in the register as a
|readfile()|-style list of lines.
- regname Requested register (e.g "x" for "xyy)
- or the empty string for an unnamed
- operation.
+ regname Requested register (e.g "x" for "xyy), or
+ empty string for an unnamed operation.
regtype Type of register as returned by
|getregtype()|.
- visual Selection is visual (as opposed to,
- e.g., via motion).
- completed_item Current selected complete item on
- |CompleteChanged|, Is `{}` when no complete
- item selected.
- height Height of popup menu on |CompleteChanged|
- width Width of popup menu on |CompleteChanged|
row Row count of popup menu on |CompleteChanged|,
relative to screen.
- col Col count of popup menu on |CompleteChanged|,
- relative to screen.
+ scope Event-specific scope name.
+ scrollbar |v:true| if popup menu has a scrollbar, or
+ |v:false| if not.
size Total number of completion items on
|CompleteChanged|.
- scrollbar Is |v:true| if popup menu have scrollbar, or
- |v:false| if not.
- changed_window Is |v:true| if the event fired while
- changing window (or tab) on |DirChanged|.
status Job status or exit code, -1 means "unknown". |TermClose|
- reason Reason for completion being done. |CompleteDone|
- complete_word The word that was selected, empty if abandoned complete.
- complete_type See |complete_info_mode|
+ visual Selection is visual (as opposed to e.g. a motion range).
+ width Width of popup menu on |CompleteChanged|
windows List of window IDs that changed on |WinResized|
]=],
},
@@ -678,13 +676,19 @@ M.vars = {
*$NVIM*
$NVIM is set by |terminal| and |jobstart()|, and is thus
a hint that the current environment is a subprocess of Nvim.
- Example: >vim
- if $NVIM
- echo nvim_get_chan_info(v:parent)
- endif
- <
- Note the contents of $NVIM may change in the future.
+ Example: a child Nvim process can detect and make requests to
+ its parent Nvim: >lua
+
+ if vim.env.NVIM then
+ local ok, chan = pcall(vim.fn.sockconnect, 'pipe', vim.env.NVIM, {rpc=true})
+ if ok and chan then
+ local client = vim.api.nvim_get_chan_info(chan).client
+ local rv = vim.rpcrequest(chan, 'nvim_exec_lua', [[return ... + 1]], { 41 })
+ vim.print(('got "%s" from parent Nvim'):format(rv))
+ end
+ end
+ <
]=],
},
shell_error = {
generated by cgit (git 2.34.1) at 2025-05-01 18:11:01 +0000