docs: getpos, getregion, lsp

4 files changed, 53 insertions, 31 deletions

diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 9ffdfe1961..3528388f11 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -3530,33 +3530,30 @@ function vim.fn.getmousepos() end
 --- @return integer
 function vim.fn.getpid() end
 
---- Get the position for String {expr}.
---- The accepted values for {expr} are:
----     .      The cursor position.
----     $      The last line in the current buffer.
+--- Gets a position, where {expr} is one of:
+---     .      Cursor position.
+---     $      Last line in the current buffer.
 ---     'x      Position of mark x (if the mark is not set, 0 is
 ---       returned for all values).
 ---     w0      First line visible in current window (one if the
 ---       display isn't updated, e.g. in silent Ex mode).
 ---     w$      Last line visible in current window (this is one
 ---       less than "w0" if no lines are visible).
----     v      When not in Visual mode, returns the cursor
----       position.  In Visual mode, returns the other end
----       of the Visual area.  A good way to think about
----       this is that in Visual mode "v" and "." complement
----       each other.  While "." refers to the cursor
----       position, "v" refers to where |v_o| would move the
----       cursor.  As a result, you can use "v" and "."
----       together to work on all of a selection in
----       characterwise Visual mode.  If the cursor is at
----       the end of a characterwise Visual area, "v" refers
----       to the start of the same Visual area.  And if the
----       cursor is at the start of a characterwise Visual
----       area, "v" refers to the end of the same Visual
----       area.  "v" differs from |'<| and |'>| in that it's
----       updated right away.
---- Note that a mark in another file can be used.  The line number
---- then applies to another buffer.
+---     v      End of the current Visual selection (unlike |'<|
+---       |'>| which give the previous, not current, Visual
+---       selection), or the cursor position if not in Visual
+---       mode.
+---
+---       To get the current selected region: >vim
+---         let region = getregionpos(getpos('v'), getpos('.'))
+--- <
+---       Explanation: in Visual mode "v" and "." complement each
+---       other.  While "." refers to the cursor position, "v"
+---       refers to where |v_o| would move the cursor.  So you can
+---       use "v" and "." together to get the selected region.
+---
+--- Note that if a mark in another file is used, the line number
+--- applies to that buffer.
 ---
 --- The result is a |List| with four numbers:
 ---     [bufnum, lnum, col, off]
@@ -3839,8 +3836,14 @@ function vim.fn.getregion(pos1, pos2, opts) end
 --- the offset of the character's first cell not included in the
 --- selection, otherwise all its cells are included.
 ---
---- Apart from the options supported by |getregion()|, {opts} also
---- supports the following:
+--- To get the current visual selection: >vim
+---   let region = getregionpos(getpos('v'), getpos('.'))
+--- <
+--- The {opts} Dict supports the following items:
+---
+---   type    See |getregion()|.
+---
+---   exclusive  See |getregion()|.
 ---
 ---   eol    If |TRUE|, indicate positions beyond
 ---       the end of a line with "col" values
diff --git a/runtime/lua/vim/filetype.lua b/runtime/lua/vim/filetype.lua
index 6fad0abde7..3e250b238e 100644
--- a/runtime/lua/vim/filetype.lua
+++ b/runtime/lua/vim/filetype.lua
@@ -3101,14 +3101,12 @@ end
 ---
 ---@param args vim.filetype.match.args Table specifying which matching strategy to use.
 ---                 Accepted keys are:
----@return string|nil # If a match was found, the matched filetype.
----@return function|nil # A function that modifies buffer state when called (for example, to set some
----                     filetype specific buffer variables). The function accepts a buffer number as
----                     its only argument.
----@return boolean|nil # Return true if a match was found by falling back to a generic configuration
----                    file (i.e., ".conf"). If true, the filetype should be set with
----                    `:setf FALLBACK conf`, which enables a later |:setf| command to override the
----                    filetype. See `:help setf` for more information.
+---@return string|nil   # The matched filetype, if any.
+---@return function|nil # A function `fun(buf: integer)` that modifies buffer state when called (for
+---                     example, to set some filetype specific buffer variables).
+---@return boolean|nil  # true if a match was found by falling back to a generic filetype
+---                     (i.e., ".conf"), which indicates the filetype should be set with
+---                     `:setf FALLBACK conf`. See |:setfiletype|.
 function M.match(args)
   vim.validate('arg', args, 'table')
 
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 1a3011e495..6773bb00ff 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -9,6 +9,15 @@
 ---     vim.print('file exists')
 ---   end
 --- <
+---
+--- *vim.fs.read()*
+--- You can use |readblob()| to get a file's contents without explicitly opening/closing it.
+---
+--- Example:
+---
+--- >lua
+---   vim.print(vim.fn.readblob('.git/config'))
+--- <
 
 local uv = vim.uv
 
diff --git a/runtime/lua/vim/keymap.lua b/runtime/lua/vim/keymap.lua
index 2afb628267..0c40abadfc 100644
--- a/runtime/lua/vim/keymap.lua
+++ b/runtime/lua/vim/keymap.lua
@@ -30,6 +30,18 @@ local keymap = {}
 --- end, { expr = true })
 --- -- Map "[%%" to a <Plug> mapping:
 --- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')
+---
+--- -- Use `getregionpos(getpos('v'))` to get the "current visual selection":
+--- vim.keymap.set('x', 'M', function()
+---   local region = vim.fn.getregionpos(vim.fn.getpos('v'), vim.fn.getpos('.'), {
+---     type = 'v',
+---     exclusive = false,
+---     eol = false,
+---   })
+---   local line1 = region[1][1][2]
+---   local line2 = region[#region][1][2]
+---   vim.print({ line1, line2 })
+--- end)
 --- ```
 ---
 ---@param mode string|string[] Mode "short-name" (see |nvim_set_keymap()|), or a list thereof.