Merge #38882 docs

5 files changed, 16 insertions, 17 deletions

diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 33774cbee0..d02970714f 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -6757,8 +6757,8 @@ vim.wo.stc = vim.wo.statuscolumn
 --- ```
 ---
 --- All fields except {item} are optional.  Use "%%" to show a literal "%"
---- char.  Setting this option to empty (`:set statusline=`) sets its
---- value to the default.
+--- char.  Setting to empty (`:set statusline=`) sets the global value to
+--- the default.
 ---
 --- 						*stl-%!*
 --- When the option starts with "%!" then it is used as an expression,
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 347862e865..2777995d58 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -3273,7 +3273,7 @@ function vim.fn.getfperm(fname) end
 --- @return integer
 function vim.fn.getfsize(fname) end
 
---- Returns the last modification time of the given file {fname}.
+--- Returns the last modification time ("mtime") of file {fname}.
 --- The value is measured as seconds since 1st Jan 1970, and may
 --- be passed to |strftime()|.  See also
 --- |localtime()| and |strftime()|.
diff --git a/runtime/lua/vim/net.lua b/runtime/lua/vim/net.lua
index d8bf5f1eb7..6d63fdc77f 100644
--- a/runtime/lua/vim/net.lua
+++ b/runtime/lua/vim/net.lua
@@ -15,9 +15,8 @@ local M = {}
 ---Buffer to save the response body to.
 ---@field outbuf? integer
 ---
----Table of custom headers to send with the request.
----Supports basic key/value header formats and empty headers as supported by curl.
----Does not support @filename style, internal header deletion (e.g: 'Header:').
+---Custom headers to send with the request. Supports basic key/value headers and empty headers as
+---supported by curl. Does not support "@filename" style, internal header deletion ("Header:").
 ---@field headers? table<string, string>
 
 ---@class vim.net.request.Response
@@ -30,12 +29,12 @@ local M = {}
 ---
 --- Examples:
 --- ```lua
---- -- Write response body to file
+--- -- Write response body to file.
 --- vim.net.request('https://neovim.io/charter/', {
 ---   outpath = 'vision.html',
 --- })
 ---
---- -- Process the response
+--- -- Process the response.
 --- vim.net.request(
 ---   'https://api.github.com/repos/neovim/neovim',
 ---   {},
@@ -46,14 +45,14 @@ local M = {}
 ---   end
 --- )
 ---
---- -- Write to both file and current buffer, but cancel it
+--- -- Write to both file and current buffer, but cancel it.
 --- local job = vim.net.request('https://neovim.io/charter/', {
 ---   outpath = 'vision.html',
 ---   outbuf = 0,
 --- })
 --- job:close()
 ---
---- -- Add custom headers in the request
+--- -- Add custom headers in the request.
 --- vim.net.request('https://neovim.io/charter/', {
 ---   headers = { Authorization = 'Bearer XYZ' },
 --- })
@@ -64,7 +63,7 @@ local M = {}
 --- @param on_response? fun(err: string?, response: vim.net.request.Response?)
 --- Callback invoked on request completion. The `body` field in the response
 --- parameter contains the raw response data (text or binary).
---- @return { close: fun() } # Table with method to cancel, similar to [vim.SystemObj].
+--- @return { close: fun() } # Object with `close()` method which cancels the request.
 function M.request(url, opts, on_response)
   vim.validate('url', url, 'string')
   vim.validate('opts', opts, 'table', true)
diff --git a/runtime/lua/vim/pos.lua b/runtime/lua/vim/pos.lua
index 718e2800e7..65e6a6678f 100644
--- a/runtime/lua/vim/pos.lua
+++ b/runtime/lua/vim/pos.lua
@@ -18,8 +18,8 @@ local validate = vim.validate
 ---
 --- Example:
 --- ```lua
---- local pos1 = vim.pos(3, 5)
---- local pos2 = vim.pos(4, 0)
+--- local pos1 = vim.pos(vim.api.nvim_get_current_buf(), 3, 5)
+--- local pos2 = vim.pos(vim.api.nvim_get_current_buf(), 4, 0)
 ---
 --- -- Operators are overloaded for comparing two `vim.Pos` objects.
 --- if pos1 < pos2 then
@@ -127,7 +127,7 @@ end
 --- local pos = vim.pos(buf, 3, 5)
 ---
 --- -- Convert to LSP position, you can call it in a method style.
---- local lsp_pos = pos:lsp('utf-16')
+--- local lsp_pos = pos:to_lsp('utf-16')
 --- ```
 ---@param position_encoding lsp.PositionEncodingKind
 function Pos:to_lsp(position_encoding)
diff --git a/runtime/lua/vim/range.lua b/runtime/lua/vim/range.lua
index 03ad1b3c52..762a33f401 100644
--- a/runtime/lua/vim/range.lua
+++ b/runtime/lua/vim/range.lua
@@ -20,13 +20,13 @@ local api = vim.api
 ---
 --- Example:
 --- ```lua
---- local pos1 = vim.pos(3, 5)
---- local pos2 = vim.pos(4, 0)
+--- local pos1 = vim.pos(vim.api.nvim_get_current_buf(), 3, 5)
+--- local pos2 = vim.pos(vim.api.nvim_get_current_buf(), 4, 0)
 ---
 --- -- Create a range from two positions.
 --- local range1 = vim.range(pos1, pos2)
 --- -- Or create a range from four integers representing start and end positions.
---- local range2 = vim.range(3, 5, 4, 0)
+--- local range2 = vim.range(vim.api.nvim_get_current_buf(), 3, 5, 4, 0)
 ---
 --- -- Because `vim.Range` is end exclusive, `range1` and `range2` both represent
 --- -- a range starting at the row 3, column 5 and ending at where the row 3 ends