commit c8b68523634d6a8375ffed77ef3b9d93231c99b1
parent 6e2b514813f465c1f4da0ee00357dd63c44d1593
Author: Justin M. Keyes <justinkz@gmail.com>
Date: Sun, 16 Nov 2025 20:36:07 -0800
docs: misc #36580
Co-authored-by: nguyenkd27 <nguyenkd27@gmail.com>
Co-authored-by: dundargoc <gocdundar@gmail.com>
Co-authored-by: Yochem van Rosmalen <git@yochem.nl>
Co-authored-by: Tuure Piitulainen <tuure.piitulainen@gmail.com>
Co-authored-by: Maria Solano <majosolano99@gmail.com>
Co-authored-by: tao <2471314@gmail.com>
Diffstat:
12 files changed, 55 insertions(+), 51 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -372,6 +372,6 @@ as context, use the `-W` argument as well.
[nvim-lspconfig/clangd]: https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#clangd
[pr-draft]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
[pr-ready]: https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/changing-the-stage-of-a-pull-request
-[run-tests]: https://github.com/neovim/neovim/blob/master/test/README.md#running-tests
+[run-tests]: https://github.com/neovim/neovim/blob/master/runtime/doc/dev_test.txt
[style-guide]: https://neovim.io/doc/user/dev_style.html#dev-style
[wiki-faq]: https://neovim.io/doc/user/faq.html
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
@@ -2261,8 +2261,10 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
will be `nvim_buf_changedtick_event`. Not for Lua
callbacks.
• {opts} (`vim.api.keyset.buf_attach`) Optional parameters.
- • on_lines: Lua callback invoked on change. Return a
- truthy value (not `false` or `nil`) to detach. Args:
+ • on_lines: Called on linewise changes. Not called on
+ buffer reload (`:checktime`, `:edit`, …), see
+ `on_reload:`. Return a |lua-truthy| value to detach.
+ Args:
• the string "lines"
• buffer id
• b:changedtick
@@ -2272,10 +2274,10 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
• byte count of previous contents
• deleted_codepoints (if `utf_sizes` is true)
• deleted_codeunits (if `utf_sizes` is true)
- • on_bytes: Lua callback invoked on change. This
- callback receives more granular information about the
- change compared to on_lines. Return a truthy value
- (not `false` or `nil`) to detach. Args:
+ • on_bytes: Called on granular changes (compared to
+ on_lines). Not called on buffer reload (`:checktime`,
+ `:edit`, …), see `on_reload:`. Return a
+ |lua-truthy| value to detach. Args:
• the string "bytes"
• buffer id
• b:changedtick
@@ -2293,16 +2295,17 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
• new end column of the changed text (if new end row
= 0, offset from start column)
• new end byte length of the changed text
- • on_changedtick: Lua callback invoked on changedtick
- increment without text change. Args:
+ • on_changedtick: Called on |changetick| increment
+ without text change. Args:
• the string "changedtick"
• buffer id
• b:changedtick
- • on_detach: Lua callback invoked on detach. Args:
+ • on_detach: Called on detach. Args:
• the string "detach"
• buffer id
- • on_reload: Lua callback invoked on reload. The entire
- buffer content should be considered changed. Args:
+ • on_reload: Called on whole-buffer load (`:checktime`,
+ `:edit`, …). Clients should typically re-fetch the
+ entire buffer contents. Args:
• the string "reload"
• buffer id
• utf_sizes: include UTF-32 and UTF-16 size of the
@@ -2312,7 +2315,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
Return: ~
(`boolean`) False if attach failed (invalid parameter, or buffer isn't
- loaded); otherwise True. TODO: LUA_API_NO_EVAL
+ loaded); otherwise True.
See also: ~
• |nvim_buf_detach()|
diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt
@@ -232,9 +232,8 @@ white space after a word, they only change up to the end of the word. This is
because Vim interprets "cw" as change-word, and a word does not include the
following white space.
-If you prefer "cw" to include the space after a word, use this mapping: >
- :map cw dwi
-Or use "caw" (see |aw|).
+If you prefer "cw" to include the space after a word, see |cpo-_| to change
+the behavior. Alternatively, use "caw" (see |aw|).
*:c* *:ch* *:change*
:{range}c[hange][!] Replace lines of text with some different text.
diff --git a/runtime/doc/dev.txt b/runtime/doc/dev.txt
@@ -1,4 +1,4 @@
-*develop.txt* Nvim
+*dev.txt* Nvim
NVIM REFERENCE MANUAL
@@ -365,6 +365,9 @@ Where possible, these patterns apply to _both_ Lua and the API:
filter(function() … end, …, opts)
-- ❌ NO:
filter(…, function() … end, opts)
+- Expose a `config(opts)` function if the module accepts user configuration.
+ If `opts` is omitted (or `nil`) it returns the current configuration.
+ - Example: See |vim.diagnostic.config()|.
- "Enable" ("toggle") interface and behavior:
- `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control the
the "global" enablement of a feature.
diff --git a/runtime/doc/dev_test.txt b/runtime/doc/dev_test.txt
@@ -1,4 +1,4 @@
-*dev_test* Nvim
+*dev_test.txt* Nvim
NVIM REFERENCE MANUAL
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
@@ -184,6 +184,10 @@ Examples: >lua
-- ba
print(string.match("foo.bar", "%.bar"))
-- .bar
+<
+ *lua-truthy*
+Only `false` and `nil` evaluate to "false" in Lua. All other values are "true".
+
==============================================================================
IMPORTING LUA MODULES *lua-module-load*
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
@@ -1377,7 +1377,7 @@ paths.
*base-directories* *xdg*
The "base" (root) directories conform to the XDG Base Directory Specification.
-https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+https://specifications.freedesktop.org/basedir/latest/
The $XDG_CONFIG_HOME, $XDG_DATA_HOME, $XDG_RUNTIME_DIR, $XDG_STATE_HOME,
$XDG_CACHE_HOME, $XDG_CONFIG_DIRS and $XDG_DATA_DIRS environment variables
are used if defined, else default values (listed below) are used.
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
@@ -182,8 +182,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
--- Else the first notification will be `nvim_buf_changedtick_event`.
--- Not for Lua callbacks.
--- @param opts vim.api.keyset.buf_attach Optional parameters.
---- - on_lines: Lua callback invoked on change.
---- Return a truthy value (not `false` or `nil`) to detach. Args:
+--- - on_lines: Called on linewise changes. Not called on buffer reload (`:checktime`,
+--- `:edit`, …), see `on_reload:`. Return a [lua-truthy] value to detach. Args:
--- - the string "lines"
--- - buffer id
--- - b:changedtick
@@ -193,10 +193,9 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
--- - byte count of previous contents
--- - deleted_codepoints (if `utf_sizes` is true)
--- - deleted_codeunits (if `utf_sizes` is true)
---- - on_bytes: Lua callback invoked on change.
---- This callback receives more granular information about the
---- change compared to on_lines.
---- Return a truthy value (not `false` or `nil`) to detach. Args:
+--- - on_bytes: Called on granular changes (compared to on_lines). Not called on buffer
+--- reload (`:checktime`, `:edit`, …), see `on_reload:`. Return a [lua-truthy] value
+--- to detach. Args:
--- - the string "bytes"
--- - buffer id
--- - b:changedtick
@@ -212,16 +211,15 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
--- - new end column of the changed text
--- (if new end row = 0, offset from start column)
--- - new end byte length of the changed text
---- - on_changedtick: Lua callback invoked on changedtick
---- increment without text change. Args:
+--- - on_changedtick: Called on [changetick] increment without text change. Args:
--- - the string "changedtick"
--- - buffer id
--- - b:changedtick
---- - on_detach: Lua callback invoked on detach. Args:
+--- - on_detach: Called on detach. Args:
--- - the string "detach"
--- - buffer id
---- - on_reload: Lua callback invoked on reload. The entire buffer
---- content should be considered changed. Args:
+--- - on_reload: Called on whole-buffer load (`:checktime`, `:edit`, …). Clients should
+--- typically re-fetch the entire buffer contents. Args:
--- - the string "reload"
--- - buffer id
--- - utf_sizes: include UTF-32 and UTF-16 size of the replaced
@@ -229,7 +227,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start
--- - preview: also attach to command preview (i.e. 'inccommand')
--- events.
--- @return boolean # False if attach failed (invalid parameter, or buffer isn't loaded);
---- otherwise True. TODO: LUA_API_NO_EVAL
+--- otherwise True.
function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end
--- Call a function with buffer as temporary current buffer.
diff --git a/runtime/lua/vim/lsp/rpc.lua b/runtime/lua/vim/lsp/rpc.lua
@@ -17,14 +17,13 @@ local function format_message_with_content_length(message)
})
end
---- Extract content-length from the header.
+--- Extract `content-length` from the header.
---
---- The structure of header fields conforms to the [HTTP semantic](https://tools.ietf.org/html/rfc7230#section-3.2).
---- i.e., `header-field = field-name : OWS field-value OWS`,
---- OWS means optional whitespace (Space/Horizontal Tab).
+--- The structure of header fields conforms to [HTTP semantics](https://tools.ietf.org/html/rfc7230#section-3.2),
+--- i.e., `header-field = field-name : OWS field-value OWS`. OWS means optional whitespace (space/horizontal tabs).
---
---- we ignore lines ending with `\n` that don't contain `content-length`, since some servers
---- write log to stdout and there's no way to avoid it.
+--- We ignore lines ending with `\n` that don't contain `content-length`, since some servers
+--- write log to standard output and there's no way to avoid it.
--- See https://github.com/neovim/neovim/pull/35743#pullrequestreview-3379705828
--- @param header string The header to parse
--- @return integer
diff --git a/src/nvim/README.md b/src/nvim/README.md
@@ -2,4 +2,4 @@
- [dev_arch.txt](../../runtime/doc/dev_arch.txt)
- [dev_tools.txt](../../runtime/doc/dev_tools.txt)
-- [develop.txt](../../runtime/doc/develop.txt)
+- [dev.txt](../../runtime/doc/dev.txt)
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
@@ -109,8 +109,8 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// Else the first notification will be `nvim_buf_changedtick_event`.
/// Not for Lua callbacks.
/// @param opts Optional parameters.
-/// - on_lines: Lua callback invoked on change.
-/// Return a truthy value (not `false` or `nil`) to detach. Args:
+/// - on_lines: Called on linewise changes. Not called on buffer reload (`:checktime`,
+/// `:edit`, …), see `on_reload:`. Return a [lua-truthy] value to detach. Args:
/// - the string "lines"
/// - buffer id
/// - b:changedtick
@@ -120,10 +120,9 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// - byte count of previous contents
/// - deleted_codepoints (if `utf_sizes` is true)
/// - deleted_codeunits (if `utf_sizes` is true)
-/// - on_bytes: Lua callback invoked on change.
-/// This callback receives more granular information about the
-/// change compared to on_lines.
-/// Return a truthy value (not `false` or `nil`) to detach. Args:
+/// - on_bytes: Called on granular changes (compared to on_lines). Not called on buffer
+/// reload (`:checktime`, `:edit`, …), see `on_reload:`. Return a [lua-truthy] value
+/// to detach. Args:
/// - the string "bytes"
/// - buffer id
/// - b:changedtick
@@ -139,16 +138,15 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// - new end column of the changed text
/// (if new end row = 0, offset from start column)
/// - new end byte length of the changed text
-/// - on_changedtick: Lua callback invoked on changedtick
-/// increment without text change. Args:
+/// - on_changedtick: Called on [changetick] increment without text change. Args:
/// - the string "changedtick"
/// - buffer id
/// - b:changedtick
-/// - on_detach: Lua callback invoked on detach. Args:
+/// - on_detach: Called on detach. Args:
/// - the string "detach"
/// - buffer id
-/// - on_reload: Lua callback invoked on reload. The entire buffer
-/// content should be considered changed. Args:
+/// - on_reload: Called on whole-buffer load (`:checktime`, `:edit`, …). Clients should
+/// typically re-fetch the entire buffer contents. Args:
/// - the string "reload"
/// - buffer id
/// - utf_sizes: include UTF-32 and UTF-16 size of the replaced
@@ -157,7 +155,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// events.
/// @param[out] err Error details, if any
/// @return False if attach failed (invalid parameter, or buffer isn't loaded);
-/// otherwise True. TODO: LUA_API_NO_EVAL
+/// otherwise True.
Boolean nvim_buf_attach(uint64_t channel_id, Buffer buffer, Boolean send_buffer,
Dict(buf_attach) *opts, Error *err)
FUNC_API_SINCE(4)
diff --git a/src/nvim/extmark.c b/src/nvim/extmark.c
@@ -509,7 +509,7 @@ void extmark_adjust(buf_T *buf, linenr_T line1, linenr_T line2, linenr_T amount,
new_row, 0, new_byte, undo);
}
-// Adjust extmarks following a text edit.
+// Adjusts extmarks after a text edit, and emits the `on_bytes` event (`:h api-buffer-updates`).
//
// @param buf
// @param start_row Start row of the region to be changed
