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>

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

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
+                       • on_lines: Called on linewise changes. Not called on
-                         truthy value (not `false` or `nil`) to detach. Args:
+                         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
+                       • on_bytes: Called on granular changes (compared to
-                         callback receives more granular information about the
+                         on_lines). Not called on buffer reload (`:checktime`,
-                         change compared to on_lines. Return a truthy value
+                         `:edit`, …), see `on_reload:`. Return a
-                         (not `false` or `nil`) to detach. Args:
+                         |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
+                       • on_changedtick: Called on |changetick| increment
-                         increment without text change. Args:
+                         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
+                       • on_reload: Called on whole-buffer load (`:checktime`,
-                         buffer content should be considered changed. Args:
+                         `: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()|

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: >
+If you prefer "cw" to include the space after a word, see |cpo-_| to change
-	:map cw dwi
+the behavior.  Alternatively, use "caw" (see |aw|).
-Or use "caw" (see |aw|).
 
 							*:c* *:ch* *:change*
 :{range}c[hange][!]	Replace lines of text with some different text.

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.

runtime/doc/dev_test.txt

@@ -1,4 +1,4 @@
-*dev_test*          Nvim
+*dev_test.txt*          Nvim
 
 
                             NVIM REFERENCE MANUAL

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*

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.

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.
+--- - on_lines: Called on linewise changes. Not called on buffer reload (`:checktime`,
----   Return a truthy value (not `false` or `nil`) to detach. Args:
+---   `: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.
+--- - on_bytes: Called on granular changes (compared to on_lines). Not called on buffer
----   This callback receives more granular information about the
+---   reload (`:checktime`, `:edit`, …), see `on_reload:`. Return a [lua-truthy] value
----   change compared to on_lines.
+---   to detach. Args:
----   Return a truthy value (not `false` or `nil`) 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
+--- - on_changedtick: Called on [changetick] increment without text change. Args:
----   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
+--- - on_reload: Called on whole-buffer load (`:checktime`, `:edit`, …). Clients should
----              content should be considered changed. Args:
+---   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.

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).
+--- 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`,
+--- i.e., `header-field = field-name : OWS field-value OWS`. OWS means optional whitespace (space/horizontal tabs).
---- OWS means optional whitespace (Space/Horizontal Tab).
 ---
---- we ignore lines ending with `\n` that don't contain `content-length`, since some servers
+--- 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.
+--- 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

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)

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.
+///             - on_lines: Called on linewise changes. Not called on buffer reload (`:checktime`,
-///               Return a truthy value (not `false` or `nil`) to detach. Args:
+///               `: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.
+///             - on_bytes: Called on granular changes (compared to on_lines). Not called on buffer
-///               This callback receives more granular information about the
+///               reload (`:checktime`, `:edit`, …), see `on_reload:`. Return a [lua-truthy] value
-///               change compared to on_lines.
+///               to detach. Args:
-///               Return a truthy value (not `false` or `nil`) 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
+///             - on_changedtick: Called on [changetick] increment without text change. Args:
-///               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
+///             - on_reload: Called on whole-buffer load (`:checktime`, `:edit`, …). Clients should
-///                          content should be considered changed. Args:
+///               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)

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