From c8b68523634d6a8375ffed77ef3b9d93231c99b1 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 16 Nov 2025 20:36:07 -0800 Subject: [PATCH] docs: misc #36580 Co-authored-by: nguyenkd27 Co-authored-by: dundargoc Co-authored-by: Yochem van Rosmalen Co-authored-by: Tuure Piitulainen Co-authored-by: Maria Solano Co-authored-by: tao <2471314@gmail.com> --- CONTRIBUTING.md | 2 +- runtime/doc/api.txt | 27 +++++++++++++++------------ runtime/doc/change.txt | 5 ++--- runtime/doc/dev.txt | 5 ++++- runtime/doc/dev_test.txt | 2 +- runtime/doc/lua.txt | 4 ++++ runtime/doc/starting.txt | 2 +- runtime/lua/vim/_meta/api.lua | 22 ++++++++++------------ runtime/lua/vim/lsp/rpc.lua | 11 +++++------ src/nvim/README.md | 2 +- src/nvim/api/buffer.c | 22 ++++++++++------------ src/nvim/extmark.c | 2 +- 12 files changed, 55 insertions(+), 51 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5b6e29a722..e7b4cc54f1 100644 --- 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 index fdd6c1e945..695018697d 100644 --- 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 index 3b255d0cc5..23e477433f 100644 --- 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 index c9ceffe089..bffe83790c 100644 --- 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 index 8b2d76d38c..e8e49b7681 100644 --- 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 index 4c361f30f3..9d1a87084e 100644 --- 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 index 8f59a2b25f..5a3c649557 100644 --- 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 index 873ae6e516..f88260bc6b 100644 --- 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 index 1b05c3e669..5d6b1512fb 100644 --- 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 index 06e4dc0b30..937e827920 100644 --- 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 index 938b79b9f9..332f11cd1e 100644 --- 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 index 8c500f8594..bcdea59ee2 100644 --- 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