docs: news

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

5 files changed, 15 insertions, 13 deletions

diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua
index 1ce40f3340..73b3375c82 100644
--- a/runtime/lua/vim/_meta/lpeg.lua
+++ b/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/).
 ---
diff --git a/runtime/lua/vim/_meta/re.lua b/runtime/lua/vim/_meta/re.lua
index 9721e6f8c8..d16751fbbf 100644
--- a/runtime/lua/vim/_meta/re.lua
+++ b/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
diff --git a/runtime/lua/vim/lsp/inlay_hint.lua b/runtime/lua/vim/lsp/inlay_hint.lua
index 8d22859a80..f98496456b 100644
--- a/runtime/lua/vim/lsp/inlay_hint.lua
+++ b/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
diff --git a/runtime/lua/vim/snippet.lua b/runtime/lua/vim/snippet.lua
index 2d95d4203d..3d8f73f362 100644
--- a/runtime/lua/vim/snippet.lua
+++ b/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()
diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua
index e618f29f8f..270d869e43 100644
--- a/runtime/lua/vim/treesitter/languagetree.lua
+++ b/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