feat(builtin): improve types

3 files changed, 192 insertions, 45 deletions

diff --git a/runtime/lua/vim/_meta/builtin_types.lua b/runtime/lua/vim/_meta/builtin_types.lua
new file mode 100644
index 0000000000..6beaee90cc
--- /dev/null
+++ b/runtime/lua/vim/_meta/builtin_types.lua
@@ -0,0 +1,129 @@
+--- @class vim.fn.sign
+--- @field group string
+--- @field id integer
+--- @field lnum integer
+--- @field name string
+--- @field priority integer
+
+--- @class vim.fn.getbufinfo.dict
+--- @field buflisted? 0|1
+--- @field bufloaded? 0|1
+--- @field bufmodified? 0|1
+
+--- @class vim.fn.getbufinfo.ret.item
+--- @field bufnr integer
+--- @field changed 0|1
+--- @field changedtick integer
+--- @field hidden 0|1
+--- @field lastused integer
+--- @field linecount integer
+--- @field listed 0|1
+--- @field lnum integer
+--- @field loaded 0|1
+--- @field name string
+--- @field signs vim.fn.sign[]
+--- @field variables table<string,any>
+--- @field windows integer[]
+
+--- @alias vim.fn.getjumplist.ret {[1]: vim.fn.getjumplist.ret.item[], [2]: integer}
+
+--- @class vim.fn.getjumplist.ret.item
+--- @field bufnr integer
+--- @field col integer
+--- @field coladd integer
+--- @field filename? string
+--- @field lnum integer
+
+--- @class vim.fn.getmousepos.ret
+--- @field screenrow integer
+--- @field screencol integer
+--- @field winid integer
+--- @field winrow integer
+--- @field wincol integer
+--- @field line integer
+--- @field column integer
+
+--- @class vim.fn.getwininfo.ret.item
+--- @field botline integer
+--- @field bufnr integer
+--- @field height integer
+--- @field loclist integer
+--- @field quickfix integer
+--- @field tabnr integer
+--- @field terminal integer
+--- @field textoff integer
+--- @field topline integer
+--- @field variables table<string,any>
+--- @field width integer
+--- @field winbar integer
+--- @field wincol integer
+--- @field winid integer
+--- @field winnr integer
+--- @field winrow integer
+
+--- @class vim.fn.sign_define.dict
+--- @field icon string
+--- @field linehl? string
+--- @field numhl? string
+--- @field text? string
+--- @field texthl? string
+--- @field culhl? string
+
+--- @class vim.fn.sign_getdefined.ret.item
+--- @field name string
+--- @field text string
+--- @field icon? string
+--- @field texthl? string
+--- @field culhl? string
+--- @field numhl? string
+--- @field linehl? string
+
+--- @class vim.fn.sign_getplaced.dict
+--- @field group? string
+--- @field id? integer
+--- @field lnum? string
+
+--- @class vim.fn.sign_getplaced.ret.item
+--- @field buf integer
+--- @field signs vim.fn.sign[]
+
+--- @class vim.fn.sign_place.dict
+--- @field lnum? integer
+--- @field priority? integer
+
+--- @class vim.fn.sign_placelist.list.item
+--- @field buffer integer|string
+--- @field group? string
+--- @field id? integer
+--- @field lnum integer
+--- @field name string
+--- @field priority? integer
+
+--- @class vim.fn.sign_unplace.dict
+--- @field buffer? integer|string
+--- @field id? integer
+
+--- @class vim.fn.sign_unplacelist.list.item
+--- @field buffer? integer|string
+--- @field group? string
+--- @field id? integer
+
+--- @class vim.fn.winrestview.dict
+--- @field col? integer
+--- @field coladd? integer
+--- @field curswant? integer
+--- @field leftcol? integer
+--- @field lnum? integer
+--- @field skipcol? integer
+--- @field topfill? integer
+--- @field topline? integer
+
+--- @class vim.fn.winsaveview.ret
+--- @field col integer
+--- @field coladd integer
+--- @field curswant integer
+--- @field leftcol integer
+--- @field lnum integer
+--- @field skipcol integer
+--- @field topfill integer
+--- @field topline integer
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index d9d3c92a44..3f891bdb45 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -2489,7 +2489,7 @@ function vim.fn.get(dict, key, default) end
 function vim.fn.get(func, what) end
 
 --- @param buf? integer|string
---- @return any
+--- @return vim.fn.getbufinfo.ret.item[]
 function vim.fn.getbufinfo(buf) end
 
 --- Get information about buffers as a List of Dictionaries.
@@ -2557,8 +2557,8 @@ function vim.fn.getbufinfo(buf) end
 ---   getbufvar({bufnr}, '&option_name')
 --- <
 ---
---- @param dict? table<string,any>
---- @return any
+--- @param dict? vim.fn.getbufinfo.dict
+--- @return vim.fn.getbufinfo.ret.item[]
 function vim.fn.getbufinfo(dict) end
 
 --- Return a |List| with the lines starting from {lnum} to {end}
@@ -2594,9 +2594,9 @@ function vim.fn.getbufline(buf, lnum, end_) end
 --- Just like `getbufline()` but only get one line and return it
 --- as a string.
 ---
---- @param buf any
+--- @param buf integer|string
 --- @param lnum integer
---- @return any
+--- @return string
 function vim.fn.getbufoneline(buf, lnum) end
 
 --- The result is the value of option or local buffer variable
@@ -3107,7 +3107,7 @@ function vim.fn.getftype(fname) end
 ---
 --- @param winnr? integer
 --- @param tabnr? integer
---- @return any
+--- @return vim.fn.getjumplist.ret
 function vim.fn.getjumplist(winnr, tabnr) end
 
 --- Without {end} the result is a String, which is line {lnum}
@@ -3260,7 +3260,7 @@ function vim.fn.getmatches(win) end
 --- When using |getchar()| the Vim variables |v:mouse_lnum|,
 --- |v:mouse_col| and |v:mouse_winid| also provide these values.
 ---
---- @return any
+--- @return vim.fn.getmousepos.ret
 function vim.fn.getmousepos() end
 
 --- Return a Number which is the process ID of the Vim process.
@@ -3659,7 +3659,7 @@ function vim.fn.gettext(text) end
 ---       "row" from |win_screenpos()|
 ---
 --- @param winid? integer
---- @return any
+--- @return vim.fn.getwininfo.ret.item[]
 function vim.fn.getwininfo(winid) end
 
 --- The result is a |List| with two numbers, the result of
@@ -8048,8 +8048,8 @@ function vim.fn.shellescape(string, special) end
 function vim.fn.shiftwidth(col) end
 
 --- @param name string
---- @param dict? any
---- @return any
+--- @param dict? vim.fn.sign_define.dict
+--- @return 0|-1
 function vim.fn.sign_define(name, dict) end
 
 --- Define a new sign named {name} or modify the attributes of an
@@ -8097,8 +8097,8 @@ function vim.fn.sign_define(name, dict) end
 ---     \ ])
 --- <
 ---
---- @param list any
---- @return any
+--- @param list vim.fn.sign_define.dict[]
+--- @return (0|-1)[]
 function vim.fn.sign_define(list) end
 
 --- Get a list of defined signs and their attributes.
@@ -8137,7 +8137,7 @@ function vim.fn.sign_define(list) end
 --- <
 ---
 --- @param name? string
---- @return any
+--- @return vim.fn.sign_getdefined.ret.item[]
 function vim.fn.sign_getdefined(name) end
 
 --- Return a list of signs placed in a buffer or all the buffers.
@@ -8201,8 +8201,8 @@ function vim.fn.sign_getdefined(name) end
 --- <
 ---
 --- @param buf? any
---- @param dict? any
---- @return any
+--- @param dict? vim.fn.sign_getplaced.dict
+--- @return vim.fn.sign_getplaced.ret.item[]
 function vim.fn.sign_getplaced(buf, dict) end
 
 --- Open the buffer {buf} or jump to the window that contains
@@ -8220,10 +8220,10 @@ function vim.fn.sign_getplaced(buf, dict) end
 ---   call sign_jump(10, '', '')
 --- <
 ---
---- @param id any
---- @param group any
---- @param buf any
---- @return any
+--- @param id integer
+--- @param group string
+--- @param buf integer|string
+--- @return integer
 function vim.fn.sign_jump(id, group, buf) end
 
 --- Place the sign defined as {name} at line {lnum} in file or
@@ -8278,8 +8278,8 @@ function vim.fn.sign_jump(id, group, buf) end
 --- @param group any
 --- @param name string
 --- @param buf any
---- @param dict? any
---- @return any
+--- @param dict? vim.fn.sign_place.dict
+--- @return integer
 function vim.fn.sign_place(id, group, name, buf, dict) end
 
 --- Place one or more signs.  This is similar to the
@@ -8340,12 +8340,12 @@ function vim.fn.sign_place(id, group, name, buf, dict) end
 ---     \ ])
 --- <
 ---
---- @param list any
---- @return any
+--- @param list vim.fn.sign_placelist.list.item[]
+--- @return integer[]
 function vim.fn.sign_placelist(list) end
 
 --- @param name? string
---- @return any
+--- @return 0|-1
 function vim.fn.sign_undefine(name) end
 
 --- Deletes a previously defined sign {name}. This is similar to
@@ -8370,8 +8370,8 @@ function vim.fn.sign_undefine(name) end
 ---   call sign_undefine()
 --- <
 ---
---- @param list? any
---- @return any
+--- @param list? string[]
+--- @return integer[]
 function vim.fn.sign_undefine(list) end
 
 --- Remove a previously placed sign in one or more buffers.  This
@@ -8415,9 +8415,9 @@ function vim.fn.sign_undefine(list) end
 ---   " Remove all the placed signs from all the buffers
 ---   call sign_unplace('*')
 ---
---- @param group any
---- @param dict? any
---- @return any
+--- @param group string
+--- @param dict? vim.fn.sign_unplace.dict
+--- @return 0|-1
 function vim.fn.sign_unplace(group, dict) end
 
 --- Remove previously placed signs from one or more buffers.  This
@@ -8448,8 +8448,8 @@ function vim.fn.sign_unplace(group, dict) end
 ---     \ ])
 --- <
 ---
---- @param list any
---- @return any
+--- @param list vim.fn.sign_unplacelist.list.item
+--- @return (0|-1)[]
 function vim.fn.sign_unplacelist(list) end
 
 --- Simplify the file name as much as possible without changing
@@ -10469,7 +10469,7 @@ function vim.fn.winrestcmd() end
 --- If you have changed the values the result is unpredictable.
 --- If the window size changed the result won't be the same.
 ---
---- @param dict any
+--- @param dict vim.fn.winrestview.dict
 --- @return any
 function vim.fn.winrestview(dict) end
 
@@ -10499,7 +10499,7 @@ function vim.fn.winrestview(dict) end
 ---   skipcol    columns skipped
 --- Note that no option values are saved.
 ---
---- @return any
+--- @return vim.fn.winsaveview.ret
 function vim.fn.winsaveview() end
 
 --- The result is a Number, which is the width of window {nr}.
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index a769983ca0..f8d57eb6de 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -3131,6 +3131,7 @@ M.funcs = {
     name = 'getbufinfo',
     params = { { 'buf', 'integer|string' } },
     signature = 'getbufinfo([{buf}])',
+    returns = 'vim.fn.getbufinfo.ret.item[]',
   },
   getbufinfo__1 = {
     args = { 0, 1 },
@@ -3202,8 +3203,9 @@ M.funcs = {
       <
     ]=],
     name = 'getbufinfo',
-    params = { { 'dict', 'table<string,any>' } },
+    params = { { 'dict', 'vim.fn.getbufinfo.dict' } },
     signature = 'getbufinfo([{dict}])',
+    returns = 'vim.fn.getbufinfo.ret.item[]',
   },
   getbufline = {
     args = { 2, 3 },
@@ -3246,8 +3248,9 @@ M.funcs = {
       as a string.
     ]=],
     name = 'getbufoneline',
-    params = { { 'buf', 'any' }, { 'lnum', 'integer' } },
+    params = { { 'buf', 'integer|string' }, { 'lnum', 'integer' } },
     signature = 'getbufoneline({buf}, {lnum})',
+    returns = 'string',
   },
   getbufvar = {
     args = { 2, 3 },
@@ -3876,6 +3879,7 @@ M.funcs = {
     name = 'getjumplist',
     params = { { 'winnr', 'integer' }, { 'tabnr', 'integer' } },
     signature = 'getjumplist([{winnr} [, {tabnr}]])',
+    returns = 'vim.fn.getjumplist.ret',
   },
   getline = {
     args = { 1, 2 },
@@ -4046,6 +4050,7 @@ M.funcs = {
     name = 'getmousepos',
     params = {},
     signature = 'getmousepos()',
+    returns = 'vim.fn.getmousepos.ret',
   },
   getpid = {
     desc = [=[
@@ -4507,6 +4512,7 @@ M.funcs = {
     name = 'getwininfo',
     params = { { 'winid', 'integer' } },
     signature = 'getwininfo([{winid}])',
+    returns = 'vim.fn.getwininfo.ret.item[]'
   },
   getwinpos = {
     args = { 0, 1 },
@@ -9618,8 +9624,9 @@ M.funcs = {
     args = { 1, 2 },
     base = 1,
     name = 'sign_define',
-    params = { { 'name', 'string' }, { 'dict', 'any' } },
+    params = { { 'name', 'string' }, { 'dict', 'vim.fn.sign_define.dict' } },
     signature = 'sign_define({name} [, {dict}])',
+    returns = '0|-1',
   },
   sign_define__1 = {
     args = { 1, 2 },
@@ -9671,8 +9678,9 @@ M.funcs = {
       <
     ]=],
     name = 'sign_define',
-    params = { { 'list', 'any' } },
+    params = { { 'list', 'vim.fn.sign_define.dict[]' } },
     signature = 'sign_define({list})',
+    returns = '(0|-1)[]',
   },
   sign_getdefined = {
     args = { 0, 1 },
@@ -9716,6 +9724,7 @@ M.funcs = {
     name = 'sign_getdefined',
     params = { { 'name', 'string' } },
     signature = 'sign_getdefined([{name}])',
+    returns = 'vim.fn.sign_getdefined.ret.item[]',
   },
   sign_getplaced = {
     args = { 0, 2 },
@@ -9782,8 +9791,9 @@ M.funcs = {
       <
     ]=],
     name = 'sign_getplaced',
-    params = { { 'buf', 'any' }, { 'dict', 'any' } },
+    params = { { 'buf', 'any' }, { 'dict', 'vim.fn.sign_getplaced.dict' } },
     signature = 'sign_getplaced([{buf} [, {dict}]])',
+    returns = 'vim.fn.sign_getplaced.ret.item[]',
   },
   sign_jump = {
     args = 3,
@@ -9805,8 +9815,9 @@ M.funcs = {
       <
     ]=],
     name = 'sign_jump',
-    params = { { 'id', 'any' }, { 'group', 'any' }, { 'buf', 'any' } },
+    params = { { 'id', 'integer' }, { 'group', 'string' }, { 'buf', 'integer|string' } },
     signature = 'sign_jump({id}, {group}, {buf})',
+    returns = 'integer'
   },
   sign_place = {
     args = { 4, 5 },
@@ -9866,9 +9877,10 @@ M.funcs = {
       { 'group', 'any' },
       { 'name', 'string' },
       { 'buf', 'any' },
-      { 'dict', 'any' },
+      { 'dict', 'vim.fn.sign_place.dict' },
     },
     signature = 'sign_place({id}, {group}, {name}, {buf} [, {dict}])',
+    returns = 'integer'
   },
   sign_placelist = {
     args = 1,
@@ -9933,8 +9945,9 @@ M.funcs = {
       <
     ]=],
     name = 'sign_placelist',
-    params = { { 'list', 'any' } },
+    params = { { 'list', 'vim.fn.sign_placelist.list.item[]' } },
     signature = 'sign_placelist({list})',
+    returns = 'integer[]'
   },
   sign_undefine = {
     args = { 0, 1 },
@@ -9942,6 +9955,7 @@ M.funcs = {
     name = 'sign_undefine',
     params = { { 'name', 'string' } },
     signature = 'sign_undefine([{name}])',
+    returns = '0|-1',
   },
   sign_undefine__1 = {
     args = { 0, 1 },
@@ -9970,8 +9984,9 @@ M.funcs = {
       <
     ]=],
     name = 'sign_undefine',
-    params = { { 'list', 'any' } },
+    params = { { 'list', 'string[]' } },
     signature = 'sign_undefine({list})',
+    returns = 'integer[]',
   },
   sign_unplace = {
     args = { 1, 2 },
@@ -10020,8 +10035,9 @@ M.funcs = {
 
     ]=],
     name = 'sign_unplace',
-    params = { { 'group', 'any' }, { 'dict', 'any' } },
+    params = { { 'group', 'string' }, { 'dict', 'vim.fn.sign_unplace.dict' } },
     signature = 'sign_unplace({group} [, {dict}])',
+    returns = '0|-1',
   },
   sign_unplacelist = {
     args = 1,
@@ -10056,8 +10072,9 @@ M.funcs = {
       <
     ]=],
     name = 'sign_unplacelist',
-    params = { { 'list', 'any' } },
+    params = { { 'list', 'vim.fn.sign_unplacelist.list.item' } },
     signature = 'sign_unplacelist({list})',
+    returns = '(0|-1)[]',
   },
   simplify = {
     args = 1,
@@ -12554,7 +12571,7 @@ M.funcs = {
 
     ]=],
     name = 'winrestview',
-    params = { { 'dict', 'any' } },
+    params = { { 'dict', 'vim.fn.winrestview.dict' } },
     signature = 'winrestview({dict})',
   },
   winsaveview = {
@@ -12588,6 +12605,7 @@ M.funcs = {
     name = 'winsaveview',
     params = {},
     signature = 'winsaveview()',
+    returns = 'vim.fn.winsaveview.ret'
   },
   winwidth = {
     args = 1,