docs(builtin): overload functions with union return types

1 files changed, 54 insertions, 10 deletions

diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index 04d176ad1b..6bd6087a4e 100644
--- a/src/nvim/eval.lua
+++ b/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' },
     },
-    returns = 'string|table<string,any>',
     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>',
   },
   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,