From c8d1b9a2d6ef910a9c1993875723387d522e6c4a Mon Sep 17 00:00:00 2001 From: Folke Lemaitre Date: Tue, 27 Sep 2022 22:44:01 +0200 Subject: docs: added proper annotations to functions in shared.lua --- runtime/lua/vim/shared.lua | 55 +++++++++++++++++++++++++++------------------- 1 file changed, 32 insertions(+), 23 deletions(-) (limited to 'runtime/lua') diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 63a932479e..1d0a6d5406 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 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}|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 Table +---@generic T: table +---@return T[] 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 Table +---@return T[] 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 +---@param 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 +---@param t table Table +---@return T[] 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" 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 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|nil Start index on src. Defaults to 1 +---@param finish number|nil 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[] 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[] 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 -- cgit From 24a1c7f556bba35a9c31c2fdd19cf4b8c00a4395 Mon Sep 17 00:00:00 2001 From: Folke Lemaitre Date: Wed, 28 Sep 2022 09:11:21 +0200 Subject: feat: added support for optional params to lua2dox --- runtime/lua/vim/shared.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'runtime/lua') diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua index 1d0a6d5406..5566bd5e35 100644 --- a/runtime/lua/vim/shared.lua +++ b/runtime/lua/vim/shared.lua @@ -417,8 +417,8 @@ end ---@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|nil Start index on src. Defaults to 1 ----@param finish number|nil Final index on src. Defaults to `#src` +---@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({ -- cgit From 1da7b4eb699fb04cc97dec389470fd0fbd64091d Mon Sep 17 00:00:00 2001 From: Folke Lemaitre Date: Wed, 28 Sep 2022 13:22:08 +0200 Subject: feat: added support for specifying types for lua2dox --- runtime/lua/vim/shared.lua | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) (limited to 'runtime/lua') 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 Table +---@param t table (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 Table ----@return T[] List of values +---@param t table (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 Table +---@param func fun(value: T): any (function) Function +---@param t table (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 Table ----@return T[] Table of filtered values +---@param func fun(value: T): boolean (function) Function +---@param t table (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 -- cgit