docs: misc #24561

fix #24699
fix #25253

1 files changed, 76 insertions, 77 deletions

diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 0c38fa955a..9542d93789 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -534,12 +534,12 @@ function vim.tbl_flatten(t)
   return result
 end
 
---- Enumerate a table sorted by its keys.
+--- Enumerates key-value pairs of a table, ordered by key.
 ---
 ---@see Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
 ---@param t table Dict-like table
----@return function iterator over sorted keys and their values
+---@return function # |for-in| iterator over sorted keys and their values
 function vim.spairs(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
@@ -551,7 +551,6 @@ function vim.spairs(t)
   table.sort(keys)
 
   -- Return the iterator function.
-  -- TODO(justinmk): Return "iterator function, table {t}, and nil", like pairs()?
   local i = 0
   return function()
     i = i + 1
@@ -561,11 +560,14 @@ function vim.spairs(t)
   end
 end
 
---- Tests if a Lua table can be treated as an array (a table indexed by integers).
+--- Tests if `t` is an "array": a table indexed _only_ by integers (potentially non-contiguous).
 ---
---- Empty table `{}` is assumed to be an array, unless it was created by
---- |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result,
---- for example from |rpcrequest()| or |vim.fn|.
+--- If the indexes start from 1 and are contiguous then the array is also a list. |vim.tbl_islist()|
+---
+--- Empty table `{}` is an array, unless it was created by |vim.empty_dict()| or returned as
+--- a dict-like |API| or Vimscript result, for example from |rpcrequest()| or |vim.fn|.
+---
+---@see https://github.com/openresty/luajit2#tableisarray
 ---
 ---@param t table
 ---@return boolean `true` if array-like table, else `false`.
@@ -597,11 +599,13 @@ function vim.tbl_isarray(t)
   end
 end
 
---- Tests if a Lua table can be treated as a list (a table indexed by consecutive integers starting from 1).
+--- Tests if `t` is a "list": a table indexed _only_ by contiguous integers starting from 1 (what
+--- |lua-length| calls a "regular array").
+---
+--- Empty table `{}` is a list, unless it was created by |vim.empty_dict()| or returned as
+--- a dict-like |API| or Vimscript result, for example from |rpcrequest()| or |vim.fn|.
 ---
---- Empty table `{}` is assumed to be an list, unless it was created by
---- |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result,
---- for example from |rpcrequest()| or |vim.fn|.
+---@see |vim.tbl_isarray()|
 ---
 ---@param t table
 ---@return boolean `true` if list-like table, else `false`.
@@ -705,61 +709,6 @@ function vim.endswith(s, suffix)
   return #suffix == 0 or s:sub(-#suffix) == suffix
 end
 
---- Validates a parameter specification (types and values).
----
---- Usage example:
----
---- ```lua
---- function user.new(name, age, hobbies)
----   vim.validate{
----     name={name, 'string'},
----     age={age, 'number'},
----     hobbies={hobbies, 'table'},
----   }
----   ...
---- end
---- ```
----
---- Examples with explicit argument values (can be run directly):
----
---- ```lua
---- vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
----    --> NOP (success)
----
---- vim.validate{arg1={1, 'table'}}
----    --> error('arg1: expected table, got number')
----
---- vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
----    --> error('arg1: expected even number, got 3')
---- ```
----
---- If multiple types are valid they can be given as a list.
----
---- ```lua
---- vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
---- -- NOP (success)
----
---- vim.validate{arg1={1, {'string', 'table'}}}
---- -- error('arg1: expected string|table, got number')
----
---- ```
----
----@param opt table Names of parameters to validate. Each key is a parameter
----          name; each value is a tuple in one of these forms:
----          1. (arg_value, type_name, optional)
----             - arg_value: argument value
----             - type_name: string|table type name, one of: ("table", "t", "string",
----               "s", "number", "n", "boolean", "b", "function", "f", "nil",
----               "thread", "userdata") or list of them.
----             - optional: (optional) boolean, if true, `nil` is valid
----          2. (arg_value, fn, msg)
----             - arg_value: argument value
----             - fn: any function accepting one argument, returns true if and
----               only if the argument is valid. Can optionally return an additional
----               informative error message as the second returned value.
----             - msg: (optional) error string if validation fails
-function vim.validate(opt) end -- luacheck: no unused
-
 do
   local type_names = {
     ['table'] = 'table',
@@ -844,6 +793,59 @@ do
     return true, nil
   end
 
+  --- Validates a parameter specification (types and values).
+  ---
+  --- Usage example:
+  ---
+  --- ```lua
+  ---  function user.new(name, age, hobbies)
+  ---    vim.validate{
+  ---      name={name, 'string'},
+  ---      age={age, 'number'},
+  ---      hobbies={hobbies, 'table'},
+  ---    }
+  ---    ...
+  ---  end
+  --- ```
+  ---
+  --- Examples with explicit argument values (can be run directly):
+  ---
+  --- ```lua
+  ---  vim.validate{arg1={{'foo'}, 'table'}, arg2={'foo', 'string'}}
+  ---     --> NOP (success)
+  ---
+  ---  vim.validate{arg1={1, 'table'}}
+  ---     --> error('arg1: expected table, got number')
+  ---
+  ---  vim.validate{arg1={3, function(a) return (a % 2) == 0 end, 'even number'}}
+  ---     --> error('arg1: expected even number, got 3')
+  --- ```
+  ---
+  --- If multiple types are valid they can be given as a list.
+  ---
+  --- ```lua
+  ---  vim.validate{arg1={{'foo'}, {'table', 'string'}}, arg2={'foo', {'table', 'string'}}}
+  ---  -- NOP (success)
+  ---
+  ---  vim.validate{arg1={1, {'string', 'table'}}}
+  ---  -- error('arg1: expected string|table, got number')
+  ---
+  --- ```
+  ---
+  ---@param opt table Names of parameters to validate. Each key is a parameter
+  ---          name; each value is a tuple in one of these forms:
+  ---          1. (arg_value, type_name, optional)
+  ---             - arg_value: argument value
+  ---             - type_name: string|table type name, one of: ("table", "t", "string",
+  ---               "s", "number", "n", "boolean", "b", "function", "f", "nil",
+  ---               "thread", "userdata") or list of them.
+  ---             - optional: (optional) boolean, if true, `nil` is valid
+  ---          2. (arg_value, fn, msg)
+  ---             - arg_value: argument value
+  ---             - fn: any function accepting one argument, returns true if and
+  ---               only if the argument is valid. Can optionally return an additional
+  ---               informative error message as the second returned value.
+  ---             - msg: (optional) error string if validation fails
   function vim.validate(opt)
     local ok, err_msg = is_valid(opt)
     if not ok then
@@ -866,28 +868,25 @@ function vim.is_callable(f)
   return type(m.__call) == 'function'
 end
 
---- Creates a table whose members are automatically created when accessed, if they don't already
---- exist.
----
---- They mimic defaultdict in python.
+--- Creates a table whose missing keys are provided by {createfn} (like Python's "defaultdict").
 ---
---- If {create} is `nil`, this will create a defaulttable whose constructor function is
---- this function, effectively allowing to create nested tables on the fly:
+--- If {createfn} is `nil` it defaults to defaulttable() itself, so accessing nested keys creates
+--- nested tables:
 ---
 --- ```lua
 --- local a = vim.defaulttable()
 --- a.b.c = 1
 --- ```
 ---
----@param create function?(key:any):any The function called to create a missing value.
----@return table Empty table with metamethod
-function vim.defaulttable(create)
-  create = create or function(_)
+---@param createfn function?(key:any):any Provides the value for a missing `key`.
+---@return table # Empty table with `__index` metamethod.
+function vim.defaulttable(createfn)
+  createfn = createfn or function(_)
     return vim.defaulttable()
   end
   return setmetatable({}, {
     __index = function(tbl, key)
-      rawset(tbl, key, create(key))
+      rawset(tbl, key, createfn(key))
       return rawget(tbl, key)
     end,
   })