Merge remote-tracking branch 'upstream/master' into mix_20240309

1 files changed, 7 insertions, 5 deletions

diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 1093759efe..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.
@@ -276,7 +278,7 @@ end
 --- -- { 6, 12 }
 --- ```
 ---
----@param f fun(...):any Mapping function. Takes all values returned from
+---@param f fun(...):...:any Mapping function. Takes all values returned from
 ---                      the previous stage in the pipeline as arguments
 ---                      and returns one or more new values, which are used
 ---                      in the next pipeline stage. Nil return values
@@ -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