fix(iter): make pipeline termination conditions consistent (#24614)

If an iterator pipeline stage returns nil as its first return value, the
other return values are ignored and it is treated as if that stage
returned only nil (the semantics of returning nil are different between
different stages). This is consistent with how for loops work in Lua
more generally, where the for loop breaks when the first return value
from the function iterator is nil (see :h for-in for details).

1 files changed, 8 insertions, 2 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index fb92ad411e..08022c3ed6 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -3207,13 +3207,18 @@ receives as input the output values from the prior stage. The values used
 in the first stage of the pipeline depend on the type passed to this
 function:
 
-• List tables pass only the value of each element
-• Non-list (dict) tables pass both the key and value of each element
+• List tables (arrays) pass only the value of each element
+• Non-list tables (dictionaries) pass both the key and value of each
+  element
 • Function |iterator|s pass all of the values returned by their respective
   function
 • Tables with a metatable implementing |__call()| are treated as function
   iterators
 
+The iterator pipeline terminates when the original table or function
+iterator runs out of values (for function iterators, this means that the
+first value returned by the function is nil).
+
 Examples: >lua
 
    local it = vim.iter({ 1, 2, 3, 4, 5 })
@@ -3225,6 +3230,7 @@ Examples: >lua
    it:totable()
    -- { 9, 6, 3 }
 
+   -- ipairs() is a function iterator which returns both the index (i) and the value (v)
    vim.iter(ipairs({ 1, 2, 3, 4, 5 })):map(function(i, v)
      if i > 2 then return v end
    end):totable()