docs: misc #28970

7 files changed, 42 insertions, 36 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index f1d8cc8526..cd8abc2351 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -4361,6 +4361,7 @@ maparg({name} [, {mode} [, {abbr} [, {dict}]]])                       *maparg()*
 		  "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
 			      form, only present when it differs from "lhsraw"
 		  "rhs"	     The {rhs} of the mapping as typed.
+		  "callback" Lua function, if RHS was defined as such.
 		  "silent"   1 for a |:map-silent| mapping, else 0.
 		  "noremap"  1 if the {rhs} of the mapping is not remappable.
 		  "script"   1 if mapping was defined with <script>.
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index d7837dc2fe..41bb90299b 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -138,15 +138,15 @@ DOCUMENTATION                                           *dev-doc*
 - Write docstrings (as opposed to inline comments) with present tense ("Gets"),
   not imperative ("Get"). This tends to reduce ambiguity and improve clarity
   by describing "What" instead of "How". >
-    GOOD:
+    ✅ OK:
     /// Gets a highlight definition.
-    BAD:
+    ❌ NO:
     /// Get a highlight definition.
 - Avoid starting docstrings with "The" or "A" unless needed to avoid
   ambiguity. This is a visual aid and reduces noise. >
-    GOOD:
+    ✅ OK:
     /// @param dirname Path fragment before `pend`
-    BAD:
+    ❌ NO:
     /// @param dirname The path fragment before `pend`
 - Vim differences:
     - Do not prefix help tags with "nvim-". Use |vim_diff.txt| to catalog
@@ -329,13 +329,20 @@ Where possible, these patterns apply to _both_ Lua and the API:
 - When accepting a buffer id, etc., 0 means "current buffer", nil means "all
   buffers".  Likewise for window id, tabpage id, etc.
   - Examples: |vim.lsp.codelens.clear()| |vim.diagnostic.enable()|
-- Any function signature that accepts a callback function should define the
-  callback as the LAST parameter, if possible. This improves readability of
-  calls by placing the less "noisy" arguments near the start. >
-    GOOD:
-    filter(table, opts, function() … end)
-    BAD:
-    filter(function() … end, table, opts)
+- Any function signature that accepts a callback (example: |table.foreach()|)
+  should place it as the LAST parameter (after opts), if possible (or ALWAYS
+  for "continuation callbacks"—functions called exactly once).
+  - Improves readability by placing the less "noisy" arguments near the start.
+  - Consistent with luv.
+  - Useful for future async lib which transforms functions of the form
+    `function(<args>, cb(<ret)>))` => `function(<args>) -> <ret>`.
+  - Example: >lua
+    -- ✅ OK:
+    filter(…, opts, function() … end)
+    -- ❌ NO:
+    filter(function() … end, …, opts)
+    -- ❌ NO:
+    filter(…, function() … end, opts)
 - "Enable" ("toggle") interface and behavior:
   - `enable(…, nil)` and `enable(…, {buf=nil})` are synonyms and control the
     the "global" enablement of a feature.
@@ -566,10 +573,10 @@ a good name: it's idiomatic and unambiguous. If the package is named "neovim",
 it confuses users, and complicates documentation and discussions.
 
 Examples of API-client package names:
-- GOOD: nvim-racket
-- GOOD: pynvim
-- BAD:  python-client
-- BAD:  neovim_
+- ✅ OK: nvim-racket
+- ✅ OK: pynvim
+- ❌ NO: python-client
+- ❌ NO: neovim_
 
 API client implementation guidelines ~
 
diff --git a/runtime/doc/health.txt b/runtime/doc/health.txt
index e879f11351..cb70961b55 100644
--- a/runtime/doc/health.txt
+++ b/runtime/doc/health.txt
@@ -7,10 +7,10 @@
                                        Type |gO| to see the table of contents.
 
 ==============================================================================
-Checkhealth                                                           *health*
+Checkhealth                                              *vim.health* *health*
 
 
-health.vim is a minimal framework to help users troubleshoot configuration and
+vim.health is a minimal framework to help users troubleshoot configuration and
 any other environment conditions that a plugin might care about. Nvim ships
 with healthchecks for configuration, performance, python support, ruby
 support, clipboard support, and more.
@@ -49,7 +49,7 @@ Commands                                                     *health-commands*
                         :checkhealth vim*
 <
 
-Create a healthcheck                                   *health-dev* *vim.health*
+Create a healthcheck                                              *health-dev*
 
 Healthchecks are functions that check the user environment, configuration, or
 any other prerequisites that a plugin cares about. Nvim ships with
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 7f5ae06030..e820d54a9e 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1639,8 +1639,7 @@ Lua module: vim.lsp.completion                                *lsp-completion*
     Fields: ~
       • {autotrigger}?  (`boolean`) Whether to trigger completion
                         automatically. Default: false
-      • {convert}?      (`fun(item: lsp.CompletionItem): table`) An optional
-                        function used to customize the transformation of an
+      • {convert}?      (`fun(item: lsp.CompletionItem): table`) Transforms an
                         LSP CompletionItem to |complete-items|.
 
 
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index f071d67030..0a7c53a482 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -352,16 +352,14 @@ Example: >vim
 <
                                                          *lua-table-ambiguous*
 Lua tables are used as both dictionaries and lists, so it is impossible to
-determine whether empty table is meant to be empty list or empty dictionary.
-Additionally Lua does not have integer numbers. To distinguish between these
-cases there is the following agreement:
+decide whether empty table is a list or a dict. Also Lua does not have integer
+numbers. To disambiguate these cases, we define:
                                                                     *lua-list*
-0. Empty table is empty list.
-1. Table with N consecutive integer indices starting from 1 and ending with
-   N is considered a list. See also |list-iterator|.
+0. Empty table is a list. Use |vim.empty_dict()| to represent empty dict.
+1. Table with N consecutive (no `nil` values, aka "holes") integer keys 1…N is
+   a list. See also |list-iterator|.
                                                                     *lua-dict*
-2. Table with string keys, none of which contains NUL byte, is considered to
-   be a dictionary.
+2. Table with string keys, none of which contains NUL byte, is a dict.
 3. Table with string keys, at least one of which contains NUL byte, is also
    considered to be a dictionary, but this time it is converted to
    a |msgpack-special-map|.
@@ -3839,10 +3837,12 @@ argument into an *Iter* object with methods (such as |Iter:filter()| and
 chained to create iterator "pipelines": the output of each pipeline stage is
 input to the next stage. The first stage depends on the type passed to
 `vim.iter()`:
-• List tables (arrays, |lua-list|) yield only the value of each element.
-  • Holes (nil values) are allowed.
+• Lists or arrays (|lua-list|) yield only the value of each element.
+  • Holes (nil values) are allowed (but discarded).
+  • Use pairs() to treat array/list tables as dicts (preserve holes and
+    non-contiguous integer keys): `vim.iter(pairs(…))`.
   • Use |Iter:enumerate()| to also pass the index to the next stage.
-  • Or initialize with ipairs(): `vim.iter(ipairs(…))`.
+    • Or initialize with ipairs(): `vim.iter(ipairs(…))`.
 • Non-list tables (|lua-dict|) yield both the key and value of each element.
 • Function |iterator|s yield all values returned by the underlying function.
 • Tables with a |__call()| metamethod are treated as function iterators.
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 21a8d2bd91..3d1ea8548f 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -65,9 +65,8 @@ EVENTS
 
 LSP
 
-• Add convert field in |vim.lsp.completion.BufferOpts| of
-  |vim.lsp.completion.enable()| an optional function used to customize the
-  transformation of an Lsp CompletionItem to |complete-items|.
+• |vim.lsp.completion.enable()| gained the `convert` callback which enables
+  customizing the transformation of an LSP CompletionItem to |complete-items|.
 • |vim.lsp.diagnostic.from()| can be used to convert a list of
   |vim.Diagnostic| objects into their LSP diagnostic representation.
 
diff --git a/runtime/doc/provider.txt b/runtime/doc/provider.txt
index a39f4bc5d7..c43110790a 100644
--- a/runtime/doc/provider.txt
+++ b/runtime/doc/provider.txt
@@ -248,8 +248,8 @@ For Windows WSL, try this g:clipboard definition:
                 \      '*': 'clip.exe',
                 \    },
                 \   'paste': {
-                \      '+': 'powershell.exe -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
-                \      '*': 'powershell.exe -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
+                \      '+': 'powershell.exe -NoLogo -NoProfile -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
+                \      '*': 'powershell.exe -NoLogo -NoProfile -c [Console]::Out.Write($(Get-Clipboard -Raw).tostring().replace("`r", ""))',
                 \   },
                 \   'cache_enabled': 0,
                 \ }