docs: news

Set dev_xx.txt help files to use "flow" layout.

runtime/lua/vim/_meta/lpeg.lua

@@ -6,11 +6,10 @@ error('Cannot require a meta file')
 -- with types being renamed to include the vim namespace and with some descriptions made less verbose.
 
 --- @brief <pre>help
---- LPeg is a pattern-matching library for Lua, based on
---- Parsing Expression Grammars (https://bford.info/packrat/) (PEGs).
+--- LPeg is a pattern-matching library for Lua, based on Parsing Expression
+--- Grammars (PEGs). https://bford.info/packrat/
 ---
----                                                                     *lua-lpeg*
----                                                             *vim.lpeg.Pattern*
+---                                                  *lua-lpeg* *vim.lpeg.Pattern*
 --- The LPeg library for parsing expression grammars is included as `vim.lpeg`
 --- (https://www.inf.puc-rio.br/~roberto/lpeg/).
 ---

runtime/lua/vim/_meta/re.lua

@@ -8,11 +8,11 @@ error('Cannot require a meta file')
 -- See 'lpeg.html' for license
 
 --- @brief
---- The `vim.re` module provides a conventional regex-like syntax for pattern usage
---- within LPeg |vim.lpeg|.
+--- The `vim.re` module provides a conventional regex-like syntax for pattern usage within LPeg
+--- |vim.lpeg|. (Unrelated to |vim.regex| which provides Vim |regexp| from Lua.)
 ---
---- See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original
---- documentation including regex syntax and more concrete examples.
+--- See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original documentation including
+--- regex syntax and examples.
 
 --- Compiles the given {string} and returns an equivalent LPeg pattern. The given string may define
 --- either an expression or a grammar. The optional {defs} table provides extra Lua values to be used

runtime/lua/vim/lsp/inlay_hint.lua

@@ -136,7 +136,8 @@ end
 --- local hint = vim.lsp.inlay_hint.get({ bufnr = 0 })[1] -- 0 for current buffer
 ---
 --- local client = vim.lsp.get_client_by_id(hint.client_id)
---- resolved_hint = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0).result
+--- local resp = client.request_sync('inlayHint/resolve', hint.inlay_hint, 100, 0)
+--- local resolved_hint = assert(resp and resp.result, resp.err)
 --- vim.lsp.util.apply_text_edits(resolved_hint.textEdits, 0, client.encoding)
 ---
 --- location = resolved_hint.label[1].location

runtime/lua/vim/snippet.lua

@@ -532,10 +532,9 @@ end
 
 --- @alias vim.snippet.Direction -1 | 1
 
---- Jumps within the active snippet in the given direction.
---- If the jump isn't possible, the function call does nothing.
+--- Jumps to the next (or previous) placeholder in the current snippet, if possible.
 ---
---- You can use this function to navigate a snippet as follows:
+--- For example, map `<Tab>` to jump while a snippet is active:
 ---
 --- ```lua
 --- vim.keymap.set({ 'i', 's' }, '<Tab>', function()

runtime/lua/vim/treesitter/languagetree.lua

@@ -225,7 +225,10 @@ function LanguageTree:_log(...)
   self._logger('nvim', table.concat(msg, ' '))
 end
 
---- Invalidates this parser and all its children
+--- Invalidates this parser and its children.
+---
+--- Should only be called when the tracked state of the LanguageTree is not valid against the parse
+--- tree in treesitter. Doesn't clear filesystem cache. Called often, so needs to be fast.
 ---@param reload boolean|nil
 function LanguageTree:invalidate(reload)
   self._valid = false