diff options
| -rw-r--r-- | runtime/doc/lsp.txt | 18 | ||||
| -rw-r--r-- | runtime/doc/lua.txt | 26 | ||||
| -rw-r--r-- | runtime/lua/vim/shared.lua | 30 | ||||
| -rw-r--r-- | scripts/lua2dox.lua | 69 |
4 files changed, 78 insertions, 65 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 a70677cb66..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} @@ -1641,7 +1641,7 @@ gsplit({s}, {sep}, {plain}) *vim.gsplit()* string.find) Return: ~ - fun():string Iterator over the split components + (function) Iterator over the split components See also: ~ |vim.split()| @@ -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: ~ - any[] 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,7 +1717,7 @@ 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 @@ -1787,7 +1787,7 @@ tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* • {...} (table) Two or more map-like tables Return: ~ - table|table Merged table + (table) Merged table See also: ~ |vim.tbl_extend()| @@ -1813,11 +1813,11 @@ 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: ~ - any[] Table of filtered values + (table) Table of filtered values tbl_flatten({t}) *vim.tbl_flatten()* Creates a copy of a list-like table such that any nested tables are @@ -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: ~ - any[] 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 5566bd5e35..fa2af57cfc 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -63,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 fun():string 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 } }) @@ -112,7 +112,7 @@ end --- ---@param s string String to split ---@param sep string Separator or pattern ----@param kwargs {plain: boolean, trimempty: boolean}|nil 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 @@ -159,9 +159,9 @@ end --- ---@see From https://github.com/premake/premake-core/blob/master/src/base/table.lua --- ----@param t table<T, any> Table +---@param t table<T, any> (table) Table ---@generic T: table ----@return T[] List of keys +---@return T[] (list) List of keys function vim.tbl_keys(t) assert(type(t) == 'table', string.format('Expected table, got %s', type(t))) @@ -176,8 +176,8 @@ end --- However, the order of the return table of values is not guaranteed. --- ---@generic T ----@param t table<any, T> Table ----@return T[] List of values +---@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))) @@ -191,8 +191,8 @@ end --- Apply a function to all values of a table. --- ---@generic T ----@param func fun(value: T): any Function ----@param t table<any, T> Table +---@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' } }) @@ -207,9 +207,9 @@ end --- Filter a table using a predicate function --- ---@generic T ----@param func fun(value: T): boolean Function ----@param t table<any, T> Table ----@return T[] Table of filtered values +---@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' } }) @@ -313,12 +313,12 @@ end --- ---@generic T1: table ---@generic T2: table ----@param behavior "error"|"keep"|"force" Decides what to do if a key is found in more than one map: +---@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 ... T2 Two or more map-like tables ----@return T1|T2 Merged table +---@return T1|T2 (table) Merged table function vim.tbl_deep_extend(behavior, ...) return tbl_extend(behavior, true, ...) end @@ -515,10 +515,10 @@ end --- Creates a copy of a table containing only elements from start to end (inclusive) --- ---@generic T ----@param list T[] Table +---@param list T[] (list) Table ---@param start number Start range of slice ---@param finish number End range of slice ----@return T[] 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 d93bb6080f..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() @@ -408,6 +412,19 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename) local magic = string.sub(line, 4 + offset) local magic_split = string_split(magic, ' ') + if magic_split[1] == 'param' then + 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[1] == "generic" then local generic_name, generic_type = line:match("@generic%s*(%w+)%s*:?%s*(.*)") @@ -415,39 +432,35 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename) generic_type = "any" end generic[generic_name] = generic_type - end - - local type_index = 2 - if magic_split[1] == 'param' then - type_index = type_index + 1 - if magic_split[type_index] and magic_split[2]:find("%?$") then - magic_split[type_index] = magic_split[type_index] .. "|nil" - magic_split[2] = magic_split[2]:sub(1, -2) + else + local type_index = 2 + if magic_split[1] == 'param' then + type_index = type_index + 1 end - end - if magic_split[type_index] then - for k, v in pairs(generic) do - magic_split[type_index] = magic_split[type_index]:gsub(k, v) + 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 - 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, ' ') + magic = table.concat(magic_split, ' ') - if magic_split[1] ~= "generic" then outStream:writeln('/// @' .. magic) fn_magic = checkComment4fn(fn_magic,magic) end |