docs(api): improve shared lua functions docs (#17933)

runtime/lua/vim/shared.lua

@@ -15,7 +15,7 @@ local vim = vim or {}
 --- copied and will throw an error.
 ---
 ---@param orig table Table to copy
----@returns New table of copied keys and (nested) values.
+---@return table Table of copied keys and (nested) values.
 function vim.deepcopy(orig) end -- luacheck: no unused
 vim.deepcopy = (function()
   local function _id(v)
@@ -59,10 +59,10 @@ end)()
 ---@see https://www.lua.org/pil/20.2.html
 ---@see http://lua-users.org/wiki/StringLibraryTutorial
 ---
----@param s String to split
----@param sep Separator string or pattern
----@param plain If `true` use `sep` literally (passed to String.find)
----@returns Iterator over the split components
+---@param s string String to split
+---@param sep string Separator or pattern
+---@param plain boolean If `true` use `sep` literally (passed to string.find)
+---@return function Iterator over the split components
 function vim.gsplit(s, sep, plain)
   vim.validate({ s = { s, 's' }, sep = { sep, 's' }, plain = { plain, 'b', true } })
 
@@ -107,13 +107,13 @@ end
 ---
 ---@see |vim.gsplit()|
 ---
----@param s String to split
----@param sep Separator string or pattern
----@param kwargs Keyword arguments:
+---@param s string String to split
+---@param sep string Separator or pattern
+---@param kwargs table Keyword arguments:
 ---       - plain: (boolean) If `true` use `sep` literally (passed to string.find)
 ---       - trimempty: (boolean) If `true` remove empty items from the front
 ---         and back of the list
----@returns List-like table of the split components.
+---@return table List of split components
 function vim.split(s, sep, kwargs)
   local plain
   local trimempty = false
@@ -156,8 +156,8 @@ end
 ---
 ---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t Table
----@returns list of keys
+---@param t table Table
+---@return table List of keys
 function vim.tbl_keys(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
@@ -171,8 +171,8 @@ end
 --- Return a list of all values used in a table.
 --- However, the order of the return table of values is not guaranteed.
 ---
----@param t Table
----@returns list of values
+---@param t table Table
+---@return table List of values
 function vim.tbl_values(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 
@@ -185,8 +185,9 @@ end
 
 --- Apply a function to all values of a table.
 ---
----@param func function or callable table
----@param t table
+---@param func function|table Function or callable table
+---@param t table Table
+---@return table Table of transformed values
 function vim.tbl_map(func, t)
   vim.validate({ func = { func, 'c' }, t = { t, 't' } })
 
@@ -199,8 +200,9 @@ end
 
 --- Filter a table using a predicate function
 ---
----@param func function or callable table
----@param t table
+---@param func function|table Function or callable table
+---@param t table Table
+---@return table Table of filtered values
 function vim.tbl_filter(func, t)
   vim.validate({ func = { func, 'c' }, t = { t, 't' } })
 
@@ -215,9 +217,9 @@ end
 
 --- Checks if a list-like (vector) table contains `value`.
 ---
----@param t Table to check
----@param value Value to compare
----@returns true if `t` contains `value`
+---@param t table Table to check
+---@param value any Value to compare
+---@return boolean `true` if `t` contains `value`
 function vim.tbl_contains(t, value)
   vim.validate({ t = { t, 't' } })
 
@@ -233,13 +235,14 @@ end
 ---
 ---@see https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t Table to check
+---@param t table Table to check
+---@return boolean `true` if `t` is empty
 function vim.tbl_isempty(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
   return next(t) == nil
 end
 
---- we only merge empty tables or tables that are not a list
+--- We only merge empty tables or tables that are not a list
 ---@private
 local function can_merge(v)
   return type(v) == 'table' and (vim.tbl_isempty(v) or not vim.tbl_islist(v))
@@ -283,11 +286,12 @@ end
 ---
 ---@see |extend()|
 ---
----@param behavior Decides what to do if a key is found in more than one map:
+---@param behavior string Decides what to do if a key is found in more than one map:
 ---      - "error": raise an error
 ---      - "keep":  use value from the leftmost map
 ---      - "force": use value from the rightmost map
----@param ... Two or more map-like tables.
+---@param ... table Two or more map-like tables
+---@return table Merged table
 function vim.tbl_extend(behavior, ...)
   return tbl_extend(behavior, false, ...)
 end
@@ -296,22 +300,23 @@ end
 ---
 ---@see |tbl_extend()|
 ---
----@param behavior Decides what to do if a key is found in more than one map:
+---@param behavior string Decides what to do if a key is found in more than one map:
 ---      - "error": raise an error
 ---      - "keep":  use value from the leftmost map
 ---      - "force": use value from the rightmost map
----@param ... Two or more map-like tables.
+---@param ... table Two or more map-like tables
+---@return table Merged table
 function vim.tbl_deep_extend(behavior, ...)
   return tbl_extend(behavior, true, ...)
 end
 
 --- Deep compare values for equality
 ---
---- Tables are compared recursively unless they both provide the `eq` methamethod.
+--- Tables are compared recursively unless they both provide the `eq` metamethod.
 --- All other types are compared using the equality `==` operator.
----@param a first value
----@param b second value
----@returns `true` if values are equals, else `false`.
+---@param a any First value
+---@param b any Second value
+---@return boolean `true` if values are equals, else `false`
 function vim.deep_equal(a, b)
   if a == b then
     return true
@@ -338,9 +343,10 @@ end
 --- Add the reverse lookup values to an existing table.
 --- For example:
 --- ``tbl_add_reverse_lookup { A = 1 } == { [1] = 'A', A = 1 }``
---
---Do note that it *modifies* the input.
----@param o table The table to add the reverse to.
+---
+--- Note that this *modifies* the input.
+---@param o table Table to add the reverse to
+---@return table o
 function vim.tbl_add_reverse_lookup(o)
   local keys = vim.tbl_keys(o)
   for _, k in ipairs(keys) do
@@ -361,17 +367,17 @@ end
 
 --- Index into a table (first argument) via string keys passed as subsequent arguments.
 --- Return `nil` if the key does not exist.
---_
+---
 --- Examples:
 --- <pre>
 ---  vim.tbl_get({ key = { nested_key = true }}, 'key', 'nested_key') == true
 ---  vim.tbl_get({ key = {}}, 'key', 'nested_key') == nil
 --- </pre>
 ---
----@param o Table to index
----@param ... Optional strings (0 or more, variadic) via which to index the table
+---@param o table Table to index
+---@param ... string Optional strings (0 or more, variadic) via which to index the table
 ---
----@returns nested value indexed by key if it exists, else nil
+---@return any Nested value indexed by key (if it exists), else nil
 function vim.tbl_get(o, ...)
   local keys = { ... }
   if #keys == 0 then
@@ -395,11 +401,11 @@ end
 ---
 ---@see |vim.tbl_extend()|
 ---
----@param dst list which will be modified and appended to.
----@param src list from which values will be inserted.
----@param start Start index on src. defaults to 1
----@param finish Final index on src. defaults to #src
----@returns dst
+---@param dst table List which will be modified and appended to
+---@param src table List from which values will be inserted
+---@param start number Start index on src. Defaults to 1
+---@param finish number Final index on src. Defaults to `#src`
+---@return table dst
 function vim.list_extend(dst, src, start, finish)
   vim.validate({
     dst = { dst, 't' },
@@ -418,8 +424,8 @@ end
 ---
 ---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t List-like table
----@returns Flattened copy of the given list-like table.
+---@param t table List-like table
+---@return table Flattened copy of the given list-like table
 function vim.tbl_flatten(t)
   local result = {}
   local function _tbl_flatten(_t)
@@ -443,8 +449,8 @@ end
 --- |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result,
 --- for example from |rpcrequest()| or |vim.fn|.
 ---
----@param t Table
----@returns `true` if array-like table, else `false`.
+---@param t table Table
+---@return boolean `true` if array-like table, else `false`
 function vim.tbl_islist(t)
   if type(t) ~= 'table' then
     return false
@@ -480,8 +486,8 @@ end
 --- </pre>
 ---
 ---@see https://github.com/Tieske/Penlight/blob/master/lua/pl/tablex.lua
----@param t Table
----@returns Number that is the number of the value in table
+---@param t table Table
+---@return number Number of non-nil values in table
 function vim.tbl_count(t)
   vim.validate({ t = { t, 't' } })
 
@@ -494,10 +500,10 @@ end
 
 --- Creates a copy of a table containing only elements from start to end (inclusive)
 ---
----@param list table table
----@param start integer Start range of slice
----@param finish integer End range of slice
----@returns Copy of table sliced from start to finish (inclusive)
+---@param list table Table
+---@param start number Start range of slice
+---@param finish number End range of slice
+---@return table Copy of table sliced from start to finish (inclusive)
 function vim.list_slice(list, start, finish)
   local new_list = {}
   for i = start or 1, finish or #list do
@@ -509,8 +515,8 @@ end
 --- Trim whitespace (Lua pattern "%s") from both sides of a string.
 ---
 ---@see https://www.lua.org/pil/20.2.html
----@param s String to trim
----@returns String with whitespace removed from its beginning and end
+---@param s string String to trim
+---@return string String with whitespace removed from its beginning and end
 function vim.trim(s)
   vim.validate({ s = { s, 's' } })
   return s:match('^%s*(.*%S)') or ''
@@ -519,8 +525,8 @@ end
 --- Escapes magic chars in a Lua pattern.
 ---
 ---@see https://github.com/rxi/lume
----@param s  String to escape
----@returns  %-escaped pattern string
+---@param s string String to escape
+---@return string %-escaped pattern string
 function vim.pesc(s)
   vim.validate({ s = { s, 's' } })
   return s:gsub('[%(%)%.%%%+%-%*%?%[%]%^%$]', '%%%1')
@@ -528,9 +534,9 @@ end
 
 --- Tests if `s` starts with `prefix`.
 ---
----@param s (string) a string
----@param prefix (string) a prefix
----@return (boolean) true if `prefix` is a prefix of s
+---@param s string String
+---@param prefix string Prefix to match
+---@return boolean `true` if `prefix` is a prefix of `s`
 function vim.startswith(s, prefix)
   vim.validate({ s = { s, 's' }, prefix = { prefix, 's' } })
   return s:sub(1, #prefix) == prefix
@@ -538,9 +544,9 @@ end
 
 --- Tests if `s` ends with `suffix`.
 ---
----@param s (string) a string
----@param suffix (string) a suffix
----@return (boolean) true if `suffix` is a suffix of s
+---@param s string String
+---@param suffix string Suffix to match
+---@return boolean `true` if `suffix` is a suffix of `s`
 function vim.endswith(s, suffix)
   vim.validate({ s = { s, 's' }, suffix = { suffix, 's' } })
   return #suffix == 0 or s:sub(-#suffix) == suffix
@@ -582,7 +588,7 @@ end
 ---
 --- </pre>
 ---
----@param opt table of parameter names to validations. Each key is a parameter
+---@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
@@ -632,8 +638,8 @@ do
         return false, string.format('opt[%s]: expected table, got %s', param_name, type(spec))
       end
 
-      local val = spec[1] -- Argument value.
-      local types = spec[2] -- Type name, or callable.
+      local val = spec[1] -- Argument value
+      local types = spec[2] -- Type name, or callable
       local optional = (true == spec[3])
 
       if type(types) == 'string' then
@@ -641,7 +647,7 @@ do
       end
 
       if vim.is_callable(types) then
-        -- Check user-provided validation function.
+        -- Check user-provided validation function
         local valid, optional_message = types(val)
         if not valid then
           local error_message = string.format('%s: expected %s, got %s', param_name, (spec[3] or '?'), tostring(val))
@@ -685,8 +691,8 @@ do
 end
 --- Returns true if object `f` can be called as a function.
 ---
----@param f Any object
----@return true if `f` is callable, else false
+---@param f any Any object
+---@return boolean `true` if `f` is callable, else `false`
 function vim.is_callable(f)
   if type(f) == 'function' then
     return true