docs: misc #28970

5 files changed, 23 insertions, 20 deletions

diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index c7c8362bfb..7b5570cc99 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -1,17 +1,19 @@
 -- Nvim-Lua stdlib: the `vim` module (:help lua-stdlib)
 --
--- Lua code lives in one of three places:
---    1. runtime/lua/vim/ (the runtime): For "nice to have" features, e.g. the
---       `inspect` and `lpeg` modules.
---    2. runtime/lua/vim/shared.lua: pure Lua functions which always
---       are available. Used in the test runner, as well as worker threads
---       and processes launched from Nvim.
---    3. runtime/lua/vim/_editor.lua: Code which directly interacts with
---       the Nvim editor state. Only available in the main thread.
+-- Lua code lives in one of four places:
+--    1. Plugins! Not everything needs to live on "vim.*". Plugins are the correct model for
+--       non-essential features which the user may want to disable or replace with a third-party
+--       plugin. Examples: "editorconfig", "comment".
+--       - "opt-out": runtime/plugin/*.lua
+--       - "opt-in": runtime/pack/dist/opt/
+--    2. runtime/lua/vim/ (the runtime): Lazy-loaded modules. Examples: `inspect`, `lpeg`.
+--    3. runtime/lua/vim/shared.lua: pure Lua functions which always are available. Used in the test
+--       runner, as well as worker threads and processes launched from Nvim.
+--    4. runtime/lua/vim/_editor.lua: Eager-loaded code which directly interacts with the Nvim
+--       editor state. Only available in the main thread.
 --
--- Guideline: "If in doubt, put it in the runtime".
---
--- Most functions should live directly in `vim.`, not in submodules.
+-- The top level "vim.*" namespace is for fundamental Lua and editor features. Use submodules for
+-- everything else (but avoid excessive "nesting"), or plugins (see above).
 --
 -- Compatibility with Vim's `if_lua` is explicitly a non-goal.
 --
@@ -19,9 +21,7 @@
 --    - https://github.com/luafun/luafun
 --    - https://github.com/rxi/lume
 --    - http://leafo.net/lapis/reference/utilities.html
---    - https://github.com/torch/paths
 --    - https://github.com/bakpakin/Fennel (pretty print, repl)
---    - https://github.com/howl-editor/howl/tree/master/lib/howl/util
 
 -- These are for loading runtime modules lazily since they aren't available in
 -- the nvim binary as specified in executor.c
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 05b9fc2bbf..10b09333a8 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -5262,6 +5262,7 @@ function vim.fn.map(expr1, expr2) end
 ---   "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/lua/vim/health.lua b/runtime/lua/vim/health.lua
index 236f9da752..d183c82516 100644
--- a/runtime/lua/vim/health.lua
+++ b/runtime/lua/vim/health.lua
@@ -1,6 +1,6 @@
 --- @brief
 ---<pre>help
---- 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.
@@ -39,7 +39,7 @@
 ---                         :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/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 6bddf0bc5e..4bbcaf16db 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -6,10 +6,12 @@
 --- 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.
@@ -1034,7 +1036,7 @@ function Iter.new(src, ...)
       if type(k) ~= 'number' or k <= 0 or math.floor(k) ~= k then
         return Iter.new(pairs(src))
       end
-      t[#t + 1] = v
+      t[#t + 1] = v -- Coerce to list-like table.
     end
     return ArrayIter.new(t)
   end
diff --git a/runtime/lua/vim/lsp/completion.lua b/runtime/lua/vim/lsp/completion.lua
index 89d6d0e8b9..71ea2df100 100644
--- a/runtime/lua/vim/lsp/completion.lua
+++ b/runtime/lua/vim/lsp/completion.lua
@@ -597,7 +597,7 @@ end
 
 --- @class vim.lsp.completion.BufferOpts
 --- @field autotrigger? boolean Whether to trigger completion automatically. Default: false
---- @field convert? fun(item: lsp.CompletionItem): table An optional function used to customize the transformation of an LSP CompletionItem to |complete-items|.
+--- @field convert? fun(item: lsp.CompletionItem): table Transforms an LSP CompletionItem to |complete-items|.
 
 ---@param client_id integer
 ---@param bufnr integer