aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--runtime/doc/lsp.txt18
-rw-r--r--runtime/doc/lua.txt22
-rw-r--r--runtime/lua/vim/shared.lua55
-rw-r--r--scripts/lua2dox.lua75
4 files changed, 108 insertions, 62 deletions
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 6d5c51c210..ae969491f7 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -723,7 +723,7 @@ get_buffers_by_client_id({client_id})
• {client_id} (number) client id
Return: ~
- list of buffer ids
+ (list) of buffer ids
get_client_by_id({client_id}) *vim.lsp.get_client_by_id()*
Gets a client by id, or nil if the id is invalid. The returned client may
@@ -1372,8 +1372,8 @@ apply_text_document_edit({text_document_edit}, {index}, {offset_encoding})
document.
Parameters: ~
- • {text_document_edit} table: a `TextDocumentEdit` object
- • {index} number: Optional index of the edit, if from a
+ • {text_document_edit} (table) a `TextDocumentEdit` object
+ • {index} (number) Optional index of the edit, if from a
list of edits (or nil, if not from a list)
See also: ~
@@ -1463,7 +1463,7 @@ convert_signature_help_to_markdown_lines({signature_help}, {ft}, {triggers})
server. used to better determine parameter offsets
Return: ~
- list of lines of converted markdown.
+ (list) of lines of converted markdown.
See also: ~
https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocument_signatureHelp
@@ -1485,7 +1485,7 @@ get_effective_tabstop({bufnr}) *vim.lsp.util.get_effective_tabstop()*
Returns indentation size.
Parameters: ~
- • {bufnr} (number|nil): Buffer handle, defaults to current
+ • {bufnr} (number|nil) Buffer handle, defaults to current
Return: ~
(number) indentation size
@@ -1589,7 +1589,7 @@ make_position_params({window}, {offset_encoding})
cursor position.
Parameters: ~
- • {window} number|nil: window handle or 0 for current,
+ • {window} (number|nil) window handle or 0 for current,
defaults to current
• {offset_encoding} (string) utf-8|utf-16|utf-32|nil defaults to
`offset_encoding` of first client of buffer of
@@ -1609,7 +1609,7 @@ make_range_params({window}, {offset_encoding})
`textDocument/rangeFormatting`.
Parameters: ~
- • {window} number|nil: window handle or 0 for current,
+ • {window} (number|nil) window handle or 0 for current,
defaults to current
• {offset_encoding} "utf-8"|"utf-16"|"utf-32"|nil defaults to
`offset_encoding` of first client of buffer of
@@ -1624,7 +1624,7 @@ make_text_document_params({bufnr})
Creates a `TextDocumentIdentifier` object for the current buffer.
Parameters: ~
- • {bufnr} number|nil: Buffer handle, defaults to current
+ • {bufnr} (number|nil) Buffer handle, defaults to current
Return: ~
`TextDocumentIdentifier`
@@ -1854,7 +1854,7 @@ notify({method}, {params}) *vim.lsp.rpc.notify()*
Parameters: ~
• {method} (string) The invoked LSP method
- • {params} (table|nil): Parameters for the invoked LSP method
+ • {params} (table|nil) Parameters for the invoked LSP method
Return: ~
(bool) `true` if notification could be sent, `false` if not
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 8e2270bc58..801664a670 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1482,7 +1482,7 @@ on_key({fn}, {ns_id}) *vim.on_key()*
{fn} will receive the keys after mappings have been evaluated
Parameters: ~
- • {fn} function: Callback function. It should take one string
+ • {fn} (function) Callback function. It should take one string
argument. On each key press, Nvim passes the key char to
fn(). |i_CTRL-V| If {fn} is nil, it removes the callback for
the associated {ns_id}
@@ -1665,8 +1665,8 @@ list_extend({dst}, {src}, {start}, {finish}) *vim.list_extend()*
Parameters: ~
• {dst} (table) List which will be modified and appended to
• {src} (table) List from which values will be inserted
- • {start} (number) Start index on src. Defaults to 1
- • {finish} (number) Final index on src. Defaults to `#src`
+ • {start} (number|nil) Start index on src. Defaults to 1
+ • {finish} (number|nil) Final index on src. Defaults to `#src`
Return: ~
(table) dst
@@ -1679,12 +1679,12 @@ list_slice({list}, {start}, {finish}) *vim.list_slice()*
(inclusive)
Parameters: ~
- • {list} (table) Table
+ • {list} (list) Table
• {start} (number) Start range of slice
• {finish} (number) End range of slice
Return: ~
- (table) Copy of table sliced from start to finish (inclusive)
+ (list) Copy of table sliced from start to finish (inclusive)
pesc({s}) *vim.pesc()*
Escapes magic chars in |lua-patterns|.
@@ -1717,14 +1717,14 @@ split({s}, {sep}, {kwargs}) *vim.split()*
Parameters: ~
• {s} (string) String to split
• {sep} (string) Separator or pattern
- • {kwargs} split_kwargs Keyword arguments:
+ • {kwargs} (table|nil) 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
Return: ~
- (table) List of split components
+ string[] List of split components
startswith({s}, {prefix}) *vim.startswith()*
Tests if `s` starts with `prefix`.
@@ -1813,7 +1813,7 @@ tbl_filter({func}, {t}) *vim.tbl_filter()*
Filter a table using a predicate function
Parameters: ~
- • {func} function|table Function or callable table
+ • {func} (function) Function
• {t} (table) Table
Return: ~
@@ -1883,7 +1883,7 @@ tbl_keys({t}) *vim.tbl_keys()*
• {t} (table) Table
Return: ~
- (table) List of keys
+ (list) List of keys
See also: ~
From https://github.com/premake/premake-core/blob/master/src/base/table.lua
@@ -1892,7 +1892,7 @@ tbl_map({func}, {t}) *vim.tbl_map()*
Apply a function to all values of a table.
Parameters: ~
- • {func} function|table Function or callable table
+ • {func} (function) Function
• {t} (table) Table
Return: ~
@@ -1906,7 +1906,7 @@ tbl_values({t}) *vim.tbl_values()*
• {t} (table) Table
Return: ~
- (table) List of values
+ (list) List of values
trim({s}) *vim.trim()*
Trim whitespace (Lua pattern "%s") from both sides of a string.
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 63a932479e..fa2af57cfc 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -14,8 +14,9 @@ local vim = vim or {}
--- same functions as those in the input table. Userdata and threads are not
--- copied and will throw an error.
---
----@param orig table Table to copy
----@return table Table of copied keys and (nested) values.
+---@generic T: table
+---@param orig T Table to copy
+---@return T Table of copied keys and (nested) values.
function vim.deepcopy(orig) end -- luacheck: no unused
vim.deepcopy = (function()
local function _id(v)
@@ -62,7 +63,7 @@ end)()
---@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
+---@return fun():string (function) Iterator over the split components
function vim.gsplit(s, sep, plain)
vim.validate({ s = { s, 's' }, sep = { sep, 's' }, plain = { plain, 'b', true } })
@@ -111,11 +112,11 @@ end
---
---@param s string String to split
---@param sep string Separator or pattern
----@param kwargs split_kwargs Keyword arguments:
+---@param kwargs? {plain: boolean, trimempty: boolean} (table|nil) 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
----@return table List of split components
+---@return string[] List of split components
function vim.split(s, sep, kwargs)
local plain
local trimempty = false
@@ -158,8 +159,9 @@ end
---
---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua
---
----@param t table Table
----@return table List of keys
+---@param t table<T, any> (table) Table
+---@generic T: table
+---@return T[] (list) List of keys
function vim.tbl_keys(t)
assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
@@ -173,8 +175,9 @@ 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 Table
----@return table List of values
+---@generic T
+---@param t table<any, T> (table) Table
+---@return T[] (list) List of values
function vim.tbl_values(t)
assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
@@ -187,8 +190,9 @@ end
--- Apply a function to all values of a table.
---
----@param func function|table Function or callable table
----@param t table Table
+---@generic T
+---@param func fun(value: T): any (function) Function
+---@param t table<any, T> (table) Table
---@return table Table of transformed values
function vim.tbl_map(func, t)
vim.validate({ func = { func, 'c' }, t = { t, 't' } })
@@ -202,9 +206,10 @@ end
--- Filter a table using a predicate function
---
----@param func function|table Function or callable table
----@param t table Table
----@return table Table of filtered values
+---@generic T
+---@param func fun(value: T): boolean (function) Function
+---@param t table<any, T> (table) Table
+---@return T[] (table) Table of filtered values
function vim.tbl_filter(func, t)
vim.validate({ func = { func, 'c' }, t = { t, 't' } })
@@ -306,12 +311,14 @@ end
---
---@see |vim.tbl_extend()|
---
----@param behavior string Decides what to do if a key is found in more than one map:
+---@generic T1: table
+---@generic T2: table
+---@param behavior "error"|"keep"|"force" (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 ... table Two or more map-like tables
----@return table Merged table
+---@param ... T2 Two or more map-like tables
+---@return T1|T2 (table) Merged table
function vim.tbl_deep_extend(behavior, ...)
return tbl_extend(behavior, true, ...)
end
@@ -407,11 +414,12 @@ end
---
---@see |vim.tbl_extend()|
---
----@param dst table List which will be modified and appended to
+---@generic T: table
+---@param dst T 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
+---@param start? number Start index on src. Defaults to 1
+---@param finish? number Final index on src. Defaults to `#src`
+---@return T dst
function vim.list_extend(dst, src, start, finish)
vim.validate({
dst = { dst, 't' },
@@ -506,10 +514,11 @@ end
--- Creates a copy of a table containing only elements from start to end (inclusive)
---
----@param list table Table
+---@generic T
+---@param list T[] (list) 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)
+---@return T[] (list) 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
diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua
index 6a206066b8..674b42a699 100644
--- a/scripts/lua2dox.lua
+++ b/scripts/lua2dox.lua
@@ -159,6 +159,7 @@ end
--! \param Str
--! \param Pattern
--! \returns table of string fragments
+---@return string[]
local function string_split(Str, Pattern)
local splitStr = {}
local fpat = "(.-)" .. Pattern
@@ -369,6 +370,9 @@ local function checkComment4fn(Fn_magic,MagicLines)
return fn_magic
end
+
+local types = {"number", "string", "table", "list", "boolean", "function"}
+
--! \brief run the filter
function TLua2DoX_filter.readfile(this,AppStamp,Filename)
local inStream = TStream_Read()
@@ -387,10 +391,13 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
local state = '' -- luacheck: ignore 231 variable is set but never accessed.
local offset = 0
+ local generic = {}
+ local l = 0
while not (inStream:eof()) do
line = string_trim(inStream:getLine())
-- TCore_Debug_show_var('inStream',inStream)
-- TCore_Debug_show_var('line',line )
+ l = l + 1
if string.sub(line,1,2) == '--' then -- it's a comment
-- Allow people to write style similar to EmmyLua (since they are basically the same)
-- instead of silently skipping things that start with ---
@@ -405,29 +412,58 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
local magic = string.sub(line, 4 + offset)
local magic_split = string_split(magic, ' ')
-
- local type_index = 2
if magic_split[1] == 'param' then
- type_index = type_index + 1
+ for _, type in ipairs(types) do
+ magic = magic:gsub("^param%s+([a-zA-Z_?]+)%s+.*%((" .. type .. ")%)", "param %1 %2" )
+ magic = magic:gsub("^param%s+([a-zA-Z_?]+)%s+.*%((" .. type .. "|nil)%)", "param %1 %2" )
+ end
+ magic_split = string_split(magic, ' ')
+ elseif magic_split[1] == 'return' then
+ for _, type in ipairs(types) do
+ magic = magic:gsub("^return%s+.*%((" .. type .. ")%)", "return %1" )
+ magic = magic:gsub("^return%s+.*%((" .. type .. "|nil)%)", "return %1" )
+ end
+ magic_split = string_split(magic, ' ')
end
- if magic_split[type_index] == 'number' or
- magic_split[type_index] == 'number|nil' or
- magic_split[type_index] == 'string' or
- magic_split[type_index] == 'string|nil' or
- magic_split[type_index] == 'table' or
- magic_split[type_index] == 'table|nil' or
- magic_split[type_index] == 'boolean' or
- magic_split[type_index] == 'boolean|nil' or
- magic_split[type_index] == 'function' or
- magic_split[type_index] == 'function|nil'
- then
- magic_split[type_index] = '(' .. magic_split[type_index] .. ')'
- end
- magic = table.concat(magic_split, ' ')
+ if magic_split[1] == "generic" then
+ local generic_name, generic_type = line:match("@generic%s*(%w+)%s*:?%s*(.*)")
+ if generic_type == "" then
+ generic_type = "any"
+ end
+ generic[generic_name] = generic_type
+ else
+ local type_index = 2
+ if magic_split[1] == 'param' then
+ type_index = type_index + 1
+ end
+
+ if magic_split[type_index] then
+ -- fix optional parameters
+ if magic_split[type_index] and magic_split[2]:find("%?$") then
+ if not magic_split[type_index]:find("nil") then
+ magic_split[type_index] = magic_split[type_index] .. "|nil"
+ end
+ magic_split[2] = magic_split[2]:sub(1, -2)
+ end
+ -- replace generic types
+ if magic_split[type_index] then
+ for k, v in pairs(generic) do
+ magic_split[type_index] = magic_split[type_index]:gsub(k, v)
+ end
+ end
+ -- surround some types by ()
+ for _, type in ipairs(types) do
+ magic_split[type_index] = magic_split[type_index]:gsub("^(" .. type .. "|nil):?$", "(%1)")
+ magic_split[type_index] = magic_split[type_index]:gsub("^(" .. type .. "):?$", "(%1)")
+ end
+ end
- outStream:writeln('/// @' .. magic)
- fn_magic = checkComment4fn(fn_magic,magic)
+ magic = table.concat(magic_split, ' ')
+
+ outStream:writeln('/// @' .. magic)
+ fn_magic = checkComment4fn(fn_magic,magic)
+ end
elseif string.sub(line,3,3)=='-' then -- it's a nonmagic doc comment
local comment = string.sub(line,4)
outStream:writeln('/// '.. comment)
@@ -467,6 +503,7 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
fn_magic = nil
end
elseif string.find(line, '^function') or string.find(line, '^local%s+function') then
+ generic = {}
state = 'in_function' -- it's a function
local pos_fn = string.find(line,'function')
-- function
generated by cgit (git 2.34.1) at 2025-05-01 17:59:00 +0000