docs(builtin): overload functions with union return types

runtime/lua/vim/_meta/vimfn.lua

@@ -1843,7 +1843,13 @@ function vim.fn.exp(expr) end
 ---
 --- @param string string
 --- @param nosuf? boolean
---- @param list? any
+--- @param list? nil|false
+--- @return string
+function vim.fn.expand(string, nosuf, list) end
+
+--- @param string string
+--- @param nosuf boolean
+--- @param list true|number|string|table
 --- @return string|string[]
 function vim.fn.expand(string, nosuf, list) end
 
@@ -3138,7 +3144,12 @@ function vim.fn.getjumplist(winnr, tabnr) end
 --- |getbufoneline()|
 ---
 --- @param lnum integer
---- @param end_? any
+--- @param end_? nil|false
+--- @return string
+function vim.fn.getline(lnum, end_) end
+
+--- @param lnum integer
+--- @param end_ true|number|string|table
 --- @return string|string[]
 function vim.fn.getline(lnum, end_) end
 
@@ -3436,7 +3447,12 @@ function vim.fn.getqflist(what) end
 --- If {regname} is not specified, |v:register| is used.
 ---
 --- @param regname? string
---- @param list? any
+--- @param list? nil|false
+--- @return string
+function vim.fn.getreg(regname, list) end
+
+--- @param regname string
+--- @param list true|number|string|table
 --- @return string|string[]
 function vim.fn.getreg(regname, list) end
 
@@ -5067,7 +5083,14 @@ function vim.fn.map(expr1, expr2) end
 --- @param name string
 --- @param mode? string
 --- @param abbr? boolean
---- @param dict? boolean
+--- @param dict? false
+--- @return string
+function vim.fn.maparg(name, mode, abbr, dict) end
+
+--- @param name string
+--- @param mode string
+--- @param abbr boolean
+--- @param dict true
 --- @return string|table<string,any>
 function vim.fn.maparg(name, mode, abbr, dict) end
 
@@ -9317,7 +9340,12 @@ function vim.fn.strwidth(string) end
 --- A line break is included as a newline character.
 ---
 --- @param nr integer
---- @param list? integer
+--- @param list? nil
+--- @return string
+function vim.fn.submatch(nr, list) end
+
+--- @param nr integer
+--- @param list integer
 --- @return string|string[]
 function vim.fn.submatch(nr, list) end
 

scripts/gen_eval_files.lua

@@ -354,41 +354,35 @@ local function render_eval_meta(f, fun, write)
 
   local params = process_params(fun.params)
 
-  if fun.signature then
-    write('')
-    if fun.deprecated then
-      write('--- @deprecated')
-    end
-
-    local desc = fun.desc
-
-    if desc then
-      --- @type string
-      desc = desc:gsub('\n%s*\n%s*$', '\n')
-      for _, l in ipairs(split(desc)) do
-        l = l:gsub('^      ', ''):gsub('\t', '  '):gsub('@', '\\@')
-        write('--- ' .. l)
-      end
-    end
-
-    local req_args = type(fun.args) == 'table' and fun.args[1] or fun.args or 0
-
-    for i, param in ipairs(params) do
-      local pname, ptype = param[1], param[2]
-      local optional = (pname ~= '...' and i > req_args) and '?' or ''
-      write(string.format('--- @param %s%s %s', pname, optional, ptype))
-    end
-
-    if fun.returns ~= false then
-      write('--- @return ' .. (fun.returns or 'any'))
-    end
-
-    write(render_fun_sig(funname, params))
-
-    return
+  write('')
+  if fun.deprecated then
+    write('--- @deprecated')
   end
 
-  print('no doc for', funname)
+  local desc = fun.desc
+
+  if desc then
+    --- @type string
+    desc = desc:gsub('\n%s*\n%s*$', '\n')
+    for _, l in ipairs(split(desc)) do
+      l = l:gsub('^      ', ''):gsub('\t', '  '):gsub('@', '\\@')
+      write('--- ' .. l)
+    end
+  end
+
+  local req_args = type(fun.args) == 'table' and fun.args[1] or fun.args or 0
+
+  for i, param in ipairs(params) do
+    local pname, ptype = param[1], param[2]
+    local optional = (pname ~= '...' and i > req_args) and '?' or ''
+    write(string.format('--- @param %s%s %s', pname, optional, ptype))
+  end
+
+  if fun.returns ~= false then
+    write('--- @return ' .. (fun.returns or 'any'))
+  end
+
+  write(render_fun_sig(funname, params))
 end
 
 --- @type table<string,true>
@@ -398,6 +392,10 @@ local rendered_tags = {}
 --- @param fun vim.EvalFn
 --- @param write fun(line: string)
 local function render_sig_and_tag(name, fun, write)
+  if not fun.signature then
+    return
+  end
+
   local tags = { '*' .. name .. '()*' }
 
   if fun.tags then

src/nvim/eval.lua

@@ -17,7 +17,7 @@
 --- @field deprecated? true
 --- @field returns? string|false
 --- @field returns_desc? string
---- @field signature string
+--- @field signature? string
 --- @field desc? string
 --- @field params {[1]:string, [2]:string, [3]:string}[]
 --- @field lua? false Do not render type information
@@ -2348,9 +2348,20 @@ M.funcs = {
 
     ]=],
     name = 'expand',
-    params = { { 'string', 'string' }, { 'nosuf', 'boolean' }, { 'list', 'any' } },
-    returns = 'string|string[]',
+    params = { { 'string', 'string' }, { 'nosuf', 'boolean' }, { 'list', 'nil|false' } },
     signature = 'expand({string} [, {nosuf} [, {list}]])',
+    returns = 'string',
+  },
+  expand__1 = {
+    args = { 3 },
+    base = 1,
+    name = 'expand',
+    params = {
+      { 'string', 'string' },
+      { 'nosuf', 'boolean' },
+      { 'list', 'true|number|string|table' },
+    },
+    returns = 'string|string[]',
   },
   expandcmd = {
     args = { 1, 2 },
@@ -3918,9 +3929,16 @@ M.funcs = {
       |getbufoneline()|
     ]=],
     name = 'getline',
-    params = { { 'lnum', 'integer' }, { 'end', 'any' } },
-    returns = 'string|string[]',
+    params = { { 'lnum', 'integer' }, { 'end', 'nil|false' } },
     signature = 'getline({lnum} [, {end}])',
+    returns = 'string',
+  },
+  getline__1 = {
+    args = { 2 },
+    base = 1,
+    name = 'getline',
+    params = { { 'lnum', 'integer' }, { 'end', 'true|number|string|table' } },
+    returns = 'string|string[]',
   },
   getloclist = {
     args = { 1, 2 },
@@ -4249,9 +4267,16 @@ M.funcs = {
 
     ]=],
     name = 'getreg',
-    params = { { 'regname', 'string' }, { 'list', 'any' } },
-    returns = 'string|string[]',
+    params = { { 'regname', 'string' }, { 'list', 'nil|false' } },
     signature = 'getreg([{regname} [, 1 [, {list}]]])',
+    returns = 'string',
+  },
+  getreg__1 = {
+    args = { 3 },
+    base = 1,
+    name = 'getreg',
+    params = { { 'regname', 'string' }, { 'list', 'true|number|string|table' } },
+    returns = 'string|string[]',
   },
   getreginfo = {
     args = { 0, 1 },
@@ -6218,10 +6243,22 @@ M.funcs = {
       { 'name', 'string' },
       { 'mode', 'string' },
       { 'abbr', 'boolean' },
-      { 'dict', 'boolean' },
+      { 'dict', 'false' },
+    },
+    signature = 'maparg({name} [, {mode} [, {abbr} [, {dict}]]])',
+    returns = 'string',
+  },
+  maparg__1 = {
+    args = { 4 },
+    base = 1,
+    name = 'maparg',
+    params = {
+      { 'name', 'string' },
+      { 'mode', 'string' },
+      { 'abbr', 'boolean' },
+      { 'dict', 'true' },
     },
     returns = 'string|table<string,any>',
-    signature = 'maparg({name} [, {mode} [, {abbr} [, {dict}]]])',
   },
   mapcheck = {
     args = { 1, 3 },
@@ -11120,9 +11157,16 @@ M.funcs = {
 
     ]=],
     name = 'submatch',
+    params = { { 'nr', 'integer' }, { 'list', 'nil' } },
+    signature = 'submatch({nr} [, {list}])',
+    returns = 'string',
+  },
+  submatch__1 = {
+    args = { 2 },
+    base = 1,
+    name = 'submatch',
     params = { { 'nr', 'integer' }, { 'list', 'integer' } },
     returns = 'string|string[]',
-    signature = 'submatch({nr} [, {list}])',
   },
   substitute = {
     args = 4,