feat(pos): create a cursor position by using the current of a window

Problem:
`vim.pos.cursor(vim.api.nvim_get_current_buf(win), vim.api.nvim_win_get_cursor(win))`
is too verbose to create a cursor position of a window,
but it is a common use case.

Solution:
Overload `vim.pos.cursor()`, so that it accepts `win` as an argument when `pos` is omitted.

1 files changed, 10 insertions, 1 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 6effa6e7c3..c983c5798a 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -4503,15 +4503,24 @@ by |vim.Pos| objects.
 cursor({buf}, {pos})                                        *vim.pos.cursor()*
     Creates a new |vim.Pos| from cursor position (see |api-indexing|).
 
+    If {pos} is omitted, the first argument is treated as {win} instead of
+    {buf}, and the current cursor position of {win} is used.
+
     Example: >lua
+        local buf = vim.api.nvim_win_get_buf(0)
         local cursor_pos = vim.api.nvim_win_get_cursor(0)
-        local pos = vim.pos.cursor(0, cursor_pos)
+        local pos = vim.pos.cursor(buf, cursor_pos)
+        -- This is equivalent:
+        local pos = vim.pos.cursor(0)
 <
 
     Parameters: ~
       • {buf}  (`integer`)
       • {pos}  (`[integer, integer]`) (lnum, col) tuple
 
+    Overloads: ~
+      • `fun(win: integer): vim.Pos`
+
     Return: ~
         (`vim.Pos`) See |vim.Pos|.