fix(gen_vimfn_types): don't include tag before signature's line (#24492)

When signature is a bit long or there are too many tags, the tags appear
before the signature's line. Don't include the line with tags in the
previous function' docs.

Also fix lint warnings.

3 files changed, 7 insertions, 74 deletions

diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index b70e361e48..409c288036 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -135,14 +135,12 @@ function vim.fn.appendbufline(buf, lnum, text) end
 --- list is used: either the window number or the window ID.
 --- Returns -1 if the {winid} argument is invalid.
 ---
----           *argidx()*
 --- @param winid? integer
 --- @return integer
 function vim.fn.argc(winid) end
 
 --- the first file.  argc() - 1 is the last one.  See |arglist|.
 ---
----           *arglistid()*
 --- @return integer
 function vim.fn.argidx() end
 
@@ -157,7 +155,6 @@ function vim.fn.argidx() end
 --- page.
 --- {winnr} can be the window number or the |window-ID|.
 ---
----           *argv()*
 --- @param winnr? integer
 --- @param tabnr? integer
 --- @return integer
@@ -217,7 +214,6 @@ function vim.fn.asin(expr) end
 --- Can also be used as a |method|: >
 ---   GetCmd()->assert_beeps()
 --- <
----           *assert_equal()*
 --- @param cmd any
 --- @return 0|1
 function vim.fn.assert_beeps(cmd) end
@@ -240,7 +236,6 @@ function vim.fn.assert_beeps(cmd) end
 --- Can also be used as a |method|: >
 ---   mylist->assert_equal([1, 2, 3])
 ---
---- <          *assert_equalfile()*
 --- @param expected any
 --- @param actual any
 --- @param msg? any
@@ -271,7 +266,6 @@ function vim.fn.assert_equalfile() end
 ---     call assert_exception('E492:')
 ---   endtry
 --- <
----           *assert_fails()*
 --- @param error any
 --- @param msg? any
 --- @return 0|1
@@ -345,7 +339,6 @@ function vim.fn.assert_false(actual, msg) end
 --- but got {actual}".  When {msg} is present it is prefixed to
 --- that.
 ---
----             *assert_match()*
 --- @param lower any
 --- @param upper any
 --- @param actual any
@@ -387,7 +380,6 @@ function vim.fn.assert_match(pattern, actual, msg) end
 --- Can also be used as a |method|: >
 ---   GetCmd()->assert_nobeep()
 --- <
----           *assert_notequal()*
 --- @param cmd any
 --- @return 0|1
 function vim.fn.assert_nobeep(cmd) end
@@ -399,7 +391,6 @@ function vim.fn.assert_nobeep(cmd) end
 --- Can also be used as a |method|: >
 ---   mylist->assert_notequal([1, 2, 3])
 ---
---- <          *assert_notmatch()*
 --- @param expected any
 --- @param actual any
 --- @param msg? any
@@ -493,7 +484,6 @@ function vim.fn.atan2(expr1, expr2) end
 --- Can also be used as a |method|: >
 ---   GetBlob()->blob2list()
 --- <
----           *browse()*
 --- @param blob any
 --- @return any
 function vim.fn.blob2list(blob) end
@@ -508,7 +498,6 @@ function vim.fn.blob2list(blob) end
 --- An empty string is returned when the "Cancel" button is hit,
 --- something went wrong, or browsing is not possible.
 ---
----           *browsedir()*
 --- @param save any
 --- @param title any
 --- @param initdir any
@@ -660,7 +649,6 @@ function vim.fn.bufloaded(buf) end
 ---   bufname("%")    name of current buffer
 ---   bufname("file2")  name of buffer where "file2" matches.
 --- <
----           *bufnr()*
 --- @param buf? any
 --- @return string
 function vim.fn.bufname(buf) end
@@ -931,7 +919,6 @@ function vim.fn.charclass(string) end
 --- <Can also be used as a |method|: >
 ---   GetPos()->col()
 --- <
----           *charidx()*
 --- @param expr any
 --- @param winid? integer
 --- @return any
@@ -1202,7 +1189,6 @@ function vim.fn.complete_check() end
 --- <Can also be used as a |method|: >
 ---   GetItems()->complete_info()
 --- <
----         *confirm()*
 --- @param what? any
 --- @return table
 function vim.fn.complete_info(what) end
@@ -1261,7 +1247,6 @@ function vim.fn.complete_info(what) end
 --- Can also be used as a |method|in: >
 ---   BuildMessage()->confirm("&Yes\n&No")
 --- <
----           *copy()*
 --- @param msg any
 --- @param choices? any
 --- @param default? any
@@ -1554,7 +1539,6 @@ function vim.fn.dictwatcheradd(dict, pattern, callback) end
 --- arguments must match the ones passed to |dictwatcheradd()| in
 --- order for the watcher to be successfully deleted.
 ---
----           *did_filetype()*
 --- @param dict any
 --- @param pattern any
 --- @param callback any
@@ -1734,7 +1718,6 @@ function vim.fn.environ() end
 --- Can also be used as a |method|: >
 ---   GetText()->escape(' \')
 --- <
----           *eval()*
 --- @param string string
 --- @param chars any
 --- @return any
@@ -1832,7 +1815,6 @@ function vim.fn.execute(command, silent) end
 --- Can also be used as a |method|: >
 ---   GetCommand()->exepath()
 --- <
----           *exists()*
 --- @param expr any
 --- @return any
 function vim.fn.exepath(expr) end
@@ -2506,7 +2488,6 @@ function vim.fn.foldclosedend(lnum) end
 --- Can also be used as a |method|: >
 ---   GetLnum()->foldlevel()
 --- <
----           *foldtext()*
 --- @param lnum integer
 --- @return integer
 function vim.fn.foldlevel(lnum) end
@@ -2558,7 +2539,6 @@ function vim.fn.foldtextresult(lnum) end
 --- Can also be used as a |method|: >
 ---   GetName()->fullcommand()
 --- <
----         *funcref()*
 --- @param name string
 --- @return string
 function vim.fn.fullcommand(name) end
@@ -2577,7 +2557,6 @@ function vim.fn.fullcommand(name) end
 --- Can also be used as a |method|: >
 ---   GetFuncname()->funcref([arg])
 --- <
----     *function()* *partial* *E700* *E923*
 --- @param name string
 --- @param arglist? any
 --- @param dict? any
@@ -2701,7 +2680,6 @@ function vim.fn.garbagecollect(atexit) end
 ---   "args"  The list with arguments
 --- Returns zero on error.
 ---
----           *getbufinfo()*
 --- @param func any
 --- @param what any
 --- @return any
@@ -2775,7 +2753,6 @@ function vim.fn.get(func, what) end
 ---   GetBufnr()->getbufinfo()
 --- <
 ---
----           *getbufline()*
 --- @param dict? any
 --- @return any
 function vim.fn.getbufinfo(dict) end
@@ -2807,7 +2784,6 @@ function vim.fn.getbufinfo(dict) end
 --- <Can also be used as a |method|: >
 ---   GetBufnr()->getbufline(lnum)
 --- <
----           *getbufoneline()*
 --- @param buf any
 --- @param lnum integer
 --- @param end_? any
@@ -2963,7 +2939,6 @@ function vim.fn.getchar() end
 --- character itself are obtained.  Thus Shift-a results in "A"
 --- without a modifier.  Returns 0 if no modifiers are used.
 ---
----           *getcharpos()*
 --- @return integer
 function vim.fn.getcharmod() end
 
@@ -3162,7 +3137,6 @@ function vim.fn.getcmdwintype() end
 --- Can also be used as a |method|: >
 ---   GetPattern()->getcompletion('color')
 --- <
----           *getcurpos()*
 --- @param pat any
 --- @param type any
 --- @param filtered? any
@@ -3196,7 +3170,6 @@ function vim.fn.getcompletion(pat, type, filtered) end
 --- Can also be used as a |method|: >
 ---   GetWinid()->getcurpos()
 --- <
----           *getcursorcharpos()*
 --- @param winid? integer
 --- @return any
 function vim.fn.getcurpos(winid) end
@@ -3367,7 +3340,6 @@ function vim.fn.getftype(fname) end
 --- Can also be used as a |method|: >
 ---   GetWinnr()->getjumplist()
 ---
---- <          *getline()*
 --- @param winnr? integer
 --- @param tabnr? integer
 --- @return any
@@ -3528,13 +3500,11 @@ 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.
 ---
----           *getpid()*
 --- @return any
 function vim.fn.getmousepos() end
 
 --- This is a unique number, until Vim exits.
 ---
----           *getpos()*
 --- @return integer
 function vim.fn.getpid() end
 
@@ -3975,7 +3945,6 @@ function vim.fn.getwininfo(winid) end
 --- Can also be used as a |method|: >
 ---   GetTimeout()->getwinpos()
 --- <
----           *getwinposx()*
 --- @param timeout? integer
 --- @return any
 function vim.fn.getwinpos(timeout) end
@@ -3984,7 +3953,6 @@ function vim.fn.getwinpos(timeout) end
 --- -1 if the information is not available.
 --- The value can be used with `:winpos`.
 ---
----           *getwinposy()*
 --- @return integer
 function vim.fn.getwinposx() end
 
@@ -4067,7 +4035,6 @@ function vim.fn.glob(expr, nosuf, list, alllinks) end
 ---
 --- Can also be used as a |method|: >
 ---   GetExpr()->glob2regpat()
---- <            *globpath()*
 --- @param string string
 --- @return any
 function vim.fn.glob2regpat(string) end
@@ -4110,7 +4077,6 @@ function vim.fn.glob2regpat(string) end
 --- second argument: >
 ---   GetExpr()->globpath(&rtp)
 --- <
----           *has()*
 --- @param path string
 --- @param expr any
 --- @param nosuf? boolean
@@ -4391,7 +4357,6 @@ function vim.fn.hlID(name) end
 --- Can also be used as a |method|: >
 ---   GetName()->hlexists()
 --- <
----           *hlID()*
 --- @param name string
 --- @return 0|1
 function vim.fn.hlexists(name) end
@@ -4417,7 +4382,6 @@ function vim.fn.hostname() end
 --- Can also be used as a |method|: >
 ---   GetText()->iconv('latin1', 'utf-8')
 --- <
----           *indent()*
 --- @param string string
 --- @param from any
 --- @param to any
@@ -5067,7 +5031,6 @@ function vim.fn.keys(dict) end
 --- Can also be used as a |method|: >
 ---   "\<C-Home>"->keytrans()
 ---
---- <          *len()* *E701*
 --- @param string string
 --- @return any
 function vim.fn.keytrans(string) end
@@ -5088,7 +5051,6 @@ function vim.fn.last_buffer_nr(...) end
 --- Can also be used as a |method|: >
 ---   mylist->len()
 ---
---- <        *libcall()* *E364* *E368*
 --- @param expr any
 --- @return any
 function vim.fn.len(expr) end
@@ -5138,7 +5100,6 @@ function vim.fn.len(expr) end
 --- third argument: >
 ---   GetValue()->libcall("libc.so", "getenv")
 --- <
----           *libcallnr()*
 --- @param libname string
 --- @param funcname string
 --- @param argument any
@@ -5578,7 +5539,6 @@ function vim.fn.mapset(mode, abbr, dict) end
 ---   GetText()->match('word')
 ---   GetList()->match('word')
 --- <
----   *matchadd()* *E798* *E799* *E801* *E957*
 --- @param expr any
 --- @param pat any
 --- @param start? any
@@ -5646,7 +5606,6 @@ function vim.fn.match(expr, pat, start, count) end
 --- Can also be used as a |method|: >
 ---   GetGroup()->matchadd('TODO')
 --- <
----           *matchaddpos()*
 --- @param group any
 --- @param pattern any
 --- @param priority? any
@@ -5922,7 +5881,6 @@ function vim.fn.matchstr(expr, pat, start, count) end
 ---   GetText()->matchstrpos('word')
 --- <
 ---
----           *max()*
 --- @param expr any
 --- @param pat any
 --- @param start? any
@@ -6069,7 +6027,6 @@ function vim.fn.menu_get(path, modes) end
 ---   GetMenuName()->menu_info('v')
 ---
 ---
---- <          *min()*
 --- @param name string
 --- @param mode? string
 --- @return any
@@ -6086,7 +6043,6 @@ function vim.fn.menu_info(name, mode) end
 --- Can also be used as a |method|: >
 ---   mylist->min()
 ---
---- <          *mkdir()* *E739*
 --- @param expr any
 --- @return any
 function vim.fn.min(expr) end
@@ -6136,7 +6092,6 @@ function vim.fn.min(expr) end
 --- Can also be used as a |method|: >
 ---   GetName()->mkdir()
 --- <
----           *mode()*
 --- @param name string
 --- @param flags? string
 --- @param prot? any
@@ -6867,7 +6822,6 @@ function vim.fn.range(expr, max, stride) end
 --- Also see |readfile()| and |writefile()|.
 ---
 ---
----           *readdir()*
 --- @param fname integer
 --- @param offset? any
 --- @param size? any
@@ -6907,7 +6861,6 @@ function vim.fn.readblob(fname, offset, size) end
 ---   GetDirName()->readdir()
 --- <
 ---
----           *readfile()*
 --- @param directory any
 --- @param expr? any
 --- @return any
@@ -7120,7 +7073,6 @@ vim.fn['repeat'] = function(expr, count) end
 --- Can also be used as a |method|: >
 ---   GetName()->resolve()
 --- <
----           *reverse()*
 --- @param filename any
 --- @return any
 function vim.fn.resolve(filename) end
@@ -7325,7 +7277,6 @@ function vim.fn.screenrow() end
 --- Can also be used as a |method|: >
 ---   GetRow()->screenstring(col)
 --- <
----             *search()*
 --- @param row any
 --- @param col integer
 --- @return any
@@ -7589,7 +7540,6 @@ function vim.fn.searchcount(options) end
 --- Can also be used as a |method|: >
 ---   GetName()->searchdecl()
 --- <
----           *searchpair()*
 --- @param name string
 --- @param global? any
 --- @param thisblock? any
@@ -7974,7 +7924,6 @@ function vim.fn.setloclist(nr, list, action, what) end
 --- Can also be used as a |method|: >
 ---   GetMatches()->setmatches()
 --- <
----           *setpos()*
 --- @param list any
 --- @param win? any
 --- @return any
@@ -8150,7 +8099,6 @@ function vim.fn.setpos(expr, list) end
 --- second argument: >
 ---   GetErrorlist()->setqflist()
 --- <
----           *setreg()*
 --- @param list any
 --- @param action? any
 --- @param what? any
@@ -8553,7 +8501,6 @@ function vim.fn.sign_getdefined(name) end
 --- Can also be used as a |method|: >
 ---   GetBufname()->sign_getplaced()
 --- <
----           *sign_jump()*
 --- @param buf? any
 --- @param dict? any
 --- @return any
@@ -8576,7 +8523,6 @@ function vim.fn.sign_getplaced(buf, dict) end
 --- Can also be used as a |method|: >
 ---   GetSignid()->sign_jump()
 --- <
----           *sign_place()*
 --- @param id any
 --- @param group any
 --- @param buf any
@@ -8633,7 +8579,6 @@ function vim.fn.sign_jump(id, group, buf) end
 --- Can also be used as a |method|: >
 ---   GetSignid()->sign_place(group, name, expr)
 --- <
----           *sign_placelist()*
 --- @param id any
 --- @param group any
 --- @param name string
@@ -8996,7 +8941,6 @@ function vim.fn.sockconnect(mode, address, opts) end
 --- <For a simple expression you can use a lambda: >
 ---   eval mylist->sort({i1, i2 -> i1 - i2})
 --- <
----           *soundfold()*
 --- @param list any
 --- @param func? any
 --- @param dict? any
@@ -9013,7 +8957,6 @@ function vim.fn.sort(list, func, dict) end
 --- Can also be used as a |method|: >
 ---   GetWord()->soundfold()
 --- <
----           *spellbadword()*
 --- @param word any
 --- @return any
 function vim.fn.soundfold(word) end
@@ -9044,7 +8987,6 @@ function vim.fn.soundfold(word) end
 --- Can also be used as a |method|: >
 ---   GetText()->spellbadword()
 --- <
----           *spellsuggest()*
 --- @param sentence? any
 --- @return any
 function vim.fn.spellbadword(sentence) end
@@ -9429,7 +9371,6 @@ function vim.fn.strgetchar(str, index) end
 --- Can also be used as a |method|: >
 ---   GetHaystack()->stridx(needle)
 --- <
----           *string()*
 --- @param haystack any
 --- @param needle any
 --- @param start? any
@@ -10042,7 +9983,6 @@ function vim.fn.tabpagenr(arg) end
 --- Can also be used as a |method|: >
 ---   GetTabpage()->tabpagewinnr()
 --- <
----           *tagfiles()*
 --- @param tabarg any
 --- @param arg? any
 --- @return any
@@ -10134,7 +10074,6 @@ function vim.fn.tan(expr) end
 --- Can also be used as a |method|: >
 ---   Compute()->tanh()
 --- <
----           *timer_info()*
 --- @param expr any
 --- @return any
 function vim.fn.tanh(expr) end
@@ -10203,7 +10142,6 @@ function vim.fn.timer_info(id) end
 --- Can also be used as a |method|: >
 ---   GetTimer()->timer_pause(1)
 --- <
----         *timer_start()* *timer* *timers*
 --- @param timer any
 --- @param paused any
 --- @return any
@@ -10472,7 +10410,6 @@ function vim.fn.undotree() end
 --- Can also be used as a |method|: >
 ---   mylist->uniq()
 --- <
----           *utf16idx()*
 --- @param list any
 --- @param func? any
 --- @param dict? any
@@ -10849,7 +10786,6 @@ function vim.fn.win_screenpos(nr) end
 --- Can also be used as a |method|: >
 ---   GetWinid()->win_splitmove(target)
 --- <
----           *winbufnr()*
 --- @param nr integer
 --- @param target any
 --- @param options? table
@@ -10867,7 +10803,6 @@ function vim.fn.win_splitmove(nr, target, options) end
 --- Can also be used as a |method|: >
 ---   FindWindow()->winbufnr()->bufname()
 --- <
----           *wincol()*
 --- @param nr integer
 --- @return integer
 function vim.fn.winbufnr(nr) end
@@ -10875,7 +10810,6 @@ function vim.fn.winbufnr(nr) end
 --- cursor in the window.  This is counting screen cells from the
 --- left side of the window.  The leftmost column is one.
 ---
----           *windowsversion()*
 --- @return integer
 function vim.fn.wincol() end
 
@@ -10935,7 +10869,6 @@ function vim.fn.winheight(nr) end
 --- Can also be used as a |method|: >
 ---   GetTabnr()->winlayout()
 --- <
----           *winline()*
 --- @param tabnr? integer
 --- @return any
 function vim.fn.winlayout(tabnr) end
@@ -10945,7 +10878,6 @@ function vim.fn.winlayout(tabnr) end
 --- If the cursor was moved the view on the file will be updated
 --- first, this may cause a scroll.
 ---
----           *winnr()*
 --- @return integer
 function vim.fn.winline() end
 
@@ -10979,7 +10911,6 @@ function vim.fn.winline() end
 --- <Can also be used as a |method|: >
 ---   GetWinval()->winnr()
 --- <
----           *winrestcmd()*
 --- @param arg? any
 --- @return any
 function vim.fn.winnr(arg) end
@@ -10992,7 +10923,6 @@ function vim.fn.winnr(arg) end
 ---   :call MessWithWindowSizes()
 ---   :exe cmd
 --- <
----           *winrestview()*
 --- @return any
 function vim.fn.winrestcmd() end
 
@@ -11014,7 +10944,6 @@ function vim.fn.winrestcmd() end
 --- Can also be used as a |method|: >
 ---   GetView()->winrestview()
 --- <
----           *winsaveview()*
 --- @param dict any
 --- @return any
 function vim.fn.winrestview(dict) end
@@ -11089,7 +11018,6 @@ function vim.fn.winwidth(nr) end
 ---       (only in Visual mode)
 ---
 ---
----           *writefile()*
 --- @return any
 function vim.fn.wordcount() end
 
diff --git a/scripts/gen_vimfn_types.lua b/scripts/gen_vimfn_types.lua
index f0dfd0665c..32de1d3c95 100755
--- a/scripts/gen_vimfn_types.lua
+++ b/scripts/gen_vimfn_types.lua
@@ -95,6 +95,7 @@ local function process_source(source)
 
   local lines = {} --- @type string[]
   local last_f --- @type string?
+  local last_l --- @type string?
 
   for i = s, #src_lines do
     local l = src_lines[i]
@@ -104,11 +105,14 @@ local function process_source(source)
     local f = l:match('^([a-z][a-zA-Z0-9_]*)%(')
     if f then
       if last_f then
+        if last_l and last_l:find('*' .. f .. '()*', 1, true) then
+          lines[#lines] = nil
+        end
         funcs[last_f].desc = lines
       end
       last_f = f
       local sig = l:match('[^)]+%)')
-      local params = {} --- @type string[]
+      local params = {} --- @type table[]
       if sig then
         for param in string.gmatch(sig, '{([a-z][a-zA-Z0-9_]*)}') do
           local t = ARG_NAME_TYPES[param] or 'any'
@@ -125,6 +129,7 @@ local function process_source(source)
     else
       lines[#lines+1] = l:gsub('^(<?)\t\t', '%1'):gsub('\t', '  ')
     end
+    last_l = l
   end
 
   if last_f then
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index a9c87e0a6d..173c99e271 100644
--- a/src/nvim/eval.lua
+++ b/src/nvim/eval.lua
@@ -12,7 +12,7 @@
 --- @field func? string Name of the C function which implements the Vimscript function. Defaults to
 ---       `f_{funcname}`.
 --- @field fast? boolean Function can run in |api-fast| events. Defaults to false.
---- @field deprecated? string[]|true
+--- @field deprecated? string[]
 --- @field returns? string|false
 
 -- Usable with the base key: use the last function argument as the method base.