Merge pull request #20496 from ehllie/runtime_annotations

docs(docstrings): fix runtime type annotations

4 files changed, 51 insertions, 31 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 5898d04a73..8e2270bc58 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1416,11 +1416,11 @@ defer_fn({fn}, {timeout})                                     *vim.defer_fn()*
     are safe to call.
 
     Parameters: ~
-      • {fn}       Callback to call once `timeout` expires
-      • {timeout}  Number of milliseconds to wait before calling `fn`
+      • {fn}       (function) Callback to call once `timeout` expires
+      • {timeout}  integer Number of milliseconds to wait before calling `fn`
 
     Return: ~
-        timer luv timer object
+        (table) timer luv timer object
 
                                                              *vim.deprecate()*
 deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
@@ -1514,18 +1514,19 @@ paste({lines}, {phase})                                          *vim.paste()*
 <
 
     Parameters: ~
-      • {lines}  |readfile()|-style list of lines to paste. |channel-lines|
-      • {phase}  -1: "non-streaming" paste: the call contains all lines. If
-                 paste is "streamed", `phase` indicates the stream state:
+      • {lines}  string[] # |readfile()|-style list of lines to paste.
+                 |channel-lines|
+      • {phase}  paste_phase -1: "non-streaming" paste: the call contains all
+                 lines. If paste is "streamed", `phase` indicates the stream state:
                  • 1: starts the paste (exactly once)
                  • 2: continues the paste (zero or more times)
                  • 3: ends the paste (exactly once)
 
     Return: ~
-        false if client should cancel the paste.
+        (boolean) # false if client should cancel the paste.
 
     See also: ~
-        |paste|
+        |paste| @alias paste_phase -1 | 1 | 2 | 3
 
 pretty_print({...})                                       *vim.pretty_print()*
     Prints given arguments in human-readable format. Example: >
@@ -1534,7 +1535,7 @@ pretty_print({...})                                       *vim.pretty_print()*
 <
 
     Return: ~
-        given arguments.
+        any # given arguments.
 
     See also: ~
         |vim.inspect()|
@@ -1545,18 +1546,26 @@ region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive})         *vim.region()*
 
     Parameters: ~
       • {bufnr}      (number) of buffer
-      • {pos1}       (line, column) tuple marking beginning of region
-      • {pos2}       (line, column) tuple marking end of region
-      • {regtype}    type of selection, see |setreg()|
+      • {pos1}       integer[] (line, column) tuple marking beginning of
+                     region
+      • {pos2}       integer[] (line, column) tuple marking end of region
+      • {regtype}    (string) type of selection, see |setreg()|
       • {inclusive}  (boolean) indicating whether the selection is
                      end-inclusive
 
     Return: ~
-        region lua table of the form {linenr = {startcol,endcol}}
+        table<integer, {}> region lua table of the form {linenr =
+        {startcol,endcol}}
 
 schedule_wrap({cb})                                      *vim.schedule_wrap()*
     Defers callback `cb` until the Nvim API is safe to call.
 
+    Parameters: ~
+      • {cb}  (function)
+
+    Return: ~
+        (function)
+
     See also: ~
         |lua-loop-callbacks|
         |vim.schedule()|
@@ -1700,10 +1709,15 @@ split({s}, {sep}, {kwargs})                                      *vim.split()*
       split("|x|y|z|", "|", {trimempty=true}) --> {'x', 'y', 'z'}
 <
 
+    @alias split_kwargs {plain: boolean, trimempty: boolean} | boolean | nil
+
+    See also: ~
+        |vim.gsplit()|
+
     Parameters: ~
       • {s}       (string) String to split
       • {sep}     (string) Separator or pattern
-      • {kwargs}  (table) Keyword arguments:
+      • {kwargs}  split_kwargs Keyword arguments:
                   • plain: (boolean) If `true` use `sep` literally (passed to
                     string.find)
                   • trimempty: (boolean) If `true` remove empty items from the
@@ -1712,9 +1726,6 @@ split({s}, {sep}, {kwargs})                                      *vim.split()*
     Return: ~
         (table) List of split components
 
-    See also: ~
-        |vim.gsplit()|
-
 startswith({s}, {prefix})                                   *vim.startswith()*
     Tests if `s` starts with `prefix`.
 
diff --git a/runtime/lua/vim/F.lua b/runtime/lua/vim/F.lua
index bca5ddf68b..3e370c0a84 100644
--- a/runtime/lua/vim/F.lua
+++ b/runtime/lua/vim/F.lua
@@ -2,8 +2,12 @@ local F = {}
 
 --- Returns {a} if it is not nil, otherwise returns {b}.
 ---
----@param a
----@param b
+---@generic A
+---@generic B
+---
+---@param a A
+---@param b B
+---@return A | B
 function F.if_nil(a, b)
   if a == nil then
     return b
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 96a87b8bb9..75df31004f 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -152,14 +152,15 @@ do
   --- </pre>
   ---
   ---@see |paste|
+  ---@alias paste_phase -1 | 1 | 2 | 3
   ---
-  ---@param lines  |readfile()|-style list of lines to paste. |channel-lines|
-  ---@param phase  -1: "non-streaming" paste: the call contains all lines.
+  ---@param lines  string[] # |readfile()|-style list of lines to paste. |channel-lines|
+  ---@param phase paste_phase  -1: "non-streaming" paste: the call contains all lines.
   ---              If paste is "streamed", `phase` indicates the stream state:
   ---                - 1: starts the paste (exactly once)
   ---                - 2: continues the paste (zero or more times)
   ---                - 3: ends the paste (exactly once)
-  ---@returns false if client should cancel the paste.
+  ---@returns boolean # false if client should cancel the paste.
   function vim.paste(lines, phase)
     local now = vim.loop.now()
     local is_first_chunk = phase < 2
@@ -255,6 +256,8 @@ end
 ---@see |lua-loop-callbacks|
 ---@see |vim.schedule()|
 ---@see |vim.in_fast_event()|
+---@param cb function
+---@return function
 function vim.schedule_wrap(cb)
   return function(...)
     local args = vim.F.pack_len(...)
@@ -399,11 +402,11 @@ end
 --- Get a table of lines with start, end columns for a region marked by two points
 ---
 ---@param bufnr number of buffer
----@param pos1 (line, column) tuple marking beginning of region
----@param pos2 (line, column) tuple marking end of region
----@param regtype type of selection, see |setreg()|
+---@param pos1 integer[] (line, column) tuple marking beginning of region
+---@param pos2 integer[] (line, column) tuple marking end of region
+---@param regtype string type of selection, see |setreg()|
 ---@param inclusive boolean indicating whether the selection is end-inclusive
----@return region lua table of the form {linenr = {startcol,endcol}}
+---@return table<integer, {}> region lua table of the form {linenr = {startcol,endcol}}
 function vim.region(bufnr, pos1, pos2, regtype, inclusive)
   if not vim.api.nvim_buf_is_loaded(bufnr) then
     vim.fn.bufload(bufnr)
@@ -450,9 +453,9 @@ end
 --- Use to do a one-shot timer that calls `fn`
 --- Note: The {fn} is |vim.schedule_wrap()|ped automatically, so API functions are
 --- safe to call.
----@param fn Callback to call once `timeout` expires
----@param timeout Number of milliseconds to wait before calling `fn`
----@return timer luv timer object
+---@param fn function Callback to call once `timeout` expires
+---@param timeout integer Number of milliseconds to wait before calling `fn`
+---@return table timer luv timer object
 function vim.defer_fn(fn, timeout)
   vim.validate({ fn = { fn, 'c', true } })
   local timer = vim.loop.new_timer()
@@ -758,7 +761,7 @@ end
 ---  local hl_normal = vim.pretty_print(vim.api.nvim_get_hl_by_name("Normal", true))
 ---</pre>
 ---@see |vim.inspect()|
----@return given arguments.
+---@return any # given arguments.
 function vim.pretty_print(...)
   local objects = {}
   for i = 1, select('#', ...) do
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index c5c31b6ddf..63a932479e 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -107,9 +107,11 @@ end
 ---
 ---@see |vim.gsplit()|
 ---
+---@alias split_kwargs {plain: boolean, trimempty: boolean} | boolean | nil
+---
 ---@param s string String to split
 ---@param sep string Separator or pattern
----@param kwargs table Keyword arguments:
+---@param kwargs split_kwargs 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