docs: misc

Co-authored-by: Kevin Pham <keevan.pham@gmail.com>

1 files changed, 27 insertions, 17 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 32dcd930bb..b087156766 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -70,6 +70,17 @@ https://www.lua.org/doc/cacm2018.pdf
 - Stackful coroutines enable cooperative multithreading, generators, and
   versatile control for both Lua and its host (Nvim).
 
+                                                           *iterator*
+An iterator is just a function that can be called repeatedly to get the "next"
+value of a collection (or any other |iterable|). This interface is expected by
+|for-in| loops, produced by |pairs()|, supported by |vim.iter|, etc.
+https://www.lua.org/pil/7.1.html
+
+                                                           *iterable*
+An "iterable" is anything that |vim.iter()| can consume: tables, dicts, lists,
+iterator functions, tables implementing the |__call()| metamethod, and
+|vim.iter()| objects.
+
                                                            *lua-call-function*
 Lua functions can be called in multiple ways. Consider the function: >lua
     local foo = function(a, b)
@@ -1909,7 +1920,8 @@ vim.endswith({s}, {suffix})                                   *vim.endswith()*
         (boolean) `true` if `suffix` is a suffix of `s`
 
 vim.gsplit({s}, {sep}, {opts})                                  *vim.gsplit()*
-    Splits a string at each instance of a separator.
+    Gets an |iterator| that splits a string at each instance of a separator,
+    in "lazy" fashion (as opposed to |vim.split()| which is "eager").
 
     Example: >lua
 
@@ -2065,16 +2077,17 @@ vim.spairs({t})                                                 *vim.spairs()*
     Enumerate a table sorted by its keys.
 
     Parameters: ~
-      • {t}  (table) List-like table
+      • {t}  (table) Dict-like table
 
     Return: ~
-        iterator over sorted keys and their values
+        _ iterator over sorted keys and their values
 
     See also: ~
       • Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
 
 vim.split({s}, {sep}, {opts})                                    *vim.split()*
-    Splits a string at each instance of a separator.
+    Splits a string at each instance of a separator and returns the result as
+    a table (unlike |vim.gsplit()|).
 
     Examples: >lua
 
@@ -3192,22 +3205,19 @@ vim.version.range({spec})                                *vim.version.range()*
 Lua module: vim.iter                                                *vim.iter*
 
 
-This module provides a generic interface for working with iterables:
-tables, lists, iterator functions, pair()/ipair()-like iterators, and
-`vim.iter()` objects.
-
-*vim.iter()* wraps its table or function argument into an *Iter* object
-with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
-underlying source data. These methods can be chained together to create
-iterator "pipelines". Each pipeline stage 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:
+*vim.iter()* is an interface for |iterable|s: it wraps a table or function
+argument into an *Iter* object with methods (such as |Iter:filter()| and
+|Iter:map()|) that transform the underlying source data. These methods can
+be chained together to create iterator "pipelines". Each pipeline stage
+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 tables pass both the key and value of each element
-• Function iterators pass all of the values returned by their respective
+• Non-list (dict) tables 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
+• Tables with a metatable implementing |__call()| are treated as function
   iterators
 
 Examples: >lua