docs: MAINTAIN.md, nvim_get_mark

7 files changed, 77 insertions, 58 deletions

diff --git a/MAINTAIN.md b/MAINTAIN.md
index 191ef70709..e280085aa8 100644
--- a/MAINTAIN.md
+++ b/MAINTAIN.md
@@ -128,17 +128,25 @@ These dependencies are "vendored" (inlined), we must update the sources manually
 
 We may maintain forks, if we are waiting on upstream changes: https://github.com/neovim/neovim/wiki/Deps
 
-CI
---------------
+Non-technical dependencies
+--------------------------
 
-### General
+* Domain names (held in https://namecheap.com):
+    * neovim.org
+    * neovim.io
+    * packspec.org
+    * pkgjson.org
+
+Automation (CI)
+---------------
 
-As our CI is primarily dependent on GitHub Actions at the moment, then so will
-our CI strategy be. The following guidelines have worked well for us so far:
+Our CI and automation jobs are primarily driven by GitHub Actions. Guidelines:
+
+### General
 
-* Never use a macOS runner if an Ubuntu or a Windows runner can be used
-  instead. This is because macOS runners have a [tighter restrictions on the
-  number of concurrent jobs](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits).
+* Avoid macOS if an Ubuntu or a Windows runner can be used instead. This is
+  because macOS runners have [tighter restrictions on the number of concurrent
+  jobs](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits).
 
 ### Runner versions
 
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 46c5f2ea18..c0e6dbc015 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -987,13 +987,14 @@ nvim_get_keymap({mode})                                    *nvim_get_keymap()*
         "buffer" key is always zero.
 
 nvim_get_mark({name}, {opts})                                *nvim_get_mark()*
-    Return a tuple (row, col, buffer, buffername) representing the position of
-    the uppercase/file named mark. See |mark-motions|.
+    Returns a `(row, col, buffer, buffername)` tuple representing the position
+    of the uppercase/file named mark. "End of line" column position is
+    returned as |v:maxcol| (big number). See |mark-motions|.
 
     Marks are (1,0)-indexed. |api-indexing|
 
     Note:
-        fails with error if a lowercase or buffer local named mark is used.
+        Lowercase name (or other buffer-local mark) is an error.
 
     Parameters: ~
       • {name}  Mark name
@@ -2232,7 +2233,8 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
         Array of lines, or empty array for unloaded buffer.
 
 nvim_buf_get_mark({buffer}, {name})                      *nvim_buf_get_mark()*
-    Returns a tuple (row,col) representing the position of the named mark. See
+    Returns a `(row,col)` tuple representing the position of the named mark.
+    "End of line" column position is returned as |v:maxcol| (big number). See
     |mark-motions|.
 
     Marks are (1,0)-indexed. |api-indexing|
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 63523c32d5..f33bd3eb5c 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1476,16 +1476,18 @@ on_key({fn}, {ns_id})                                           *vim.on_key()*
     callbacks and cannot be toggled dynamically.
 
     Note:
+        {fn} will be removed on error.
+
+    Note:
         {fn} will not be cleared by |nvim_buf_clear_namespace()|
 
     Note:
         {fn} will receive the keys after mappings have been evaluated
 
     Parameters: ~
-      • {fn}     (function) Callback function. It should take one string
-                 argument. On each key press, Nvim passes the key char to
-                 fn(). |i_CTRL-V| If {fn} is nil, it removes the callback for
-                 the associated {ns_id}
+      • {fn}     fun(key: string) Function invoked on every key press.
+                 |i_CTRL-V| Returning nil removes the callback associated with
+                 namespace {ns_id}.
       • {ns_id}  integer? Namespace ID. If nil or 0, generates and returns a
                  new |nvim_create_namespace()| id.
 
@@ -1493,9 +1495,6 @@ on_key({fn}, {ns_id})                                           *vim.on_key()*
         (integer) Namespace id associated with {fn}. Or count of all callbacks
         if on_key() is called without arguments.
 
-    Note:
-        {fn} will be removed if an error occurs while calling.
-
 paste({lines}, {phase})                                          *vim.paste()*
     Paste handler, invoked by |nvim_paste()| when a conforming UI (such as the
     |TUI|) pastes text into the editor.
@@ -1543,22 +1542,26 @@ print({...})                                                     *vim.print()*
       • |:=|
 
 region({bufnr}, {pos1}, {pos2}, {regtype}, {inclusive})         *vim.region()*
-    Get a table of lines with start, end columns for a region marked by two
-    points. Input and output positions are (0,0)-indexed and indicate byte
-    positions.
+    Gets a dict of line segment ("chunk") positions for the region from `pos1`
+    to `pos2`.
+
+    Input and output positions are byte positions, (0,0)-indexed. "End of
+    line" column position (for example, |linewise| visual selection) is
+    returned as |v:maxcol| (big number).
 
     Parameters: ~
-      • {bufnr}      (integer) number of buffer
-      • {pos1}       integer[]|string start of region as a (line, column)
-                     tuple or string accepted by |getpos()|
-      • {pos2}       integer[]|string end of region as a (line, column) tuple
-                     or string accepted by |getpos()|
-      • {regtype}    (string) type of selection, see |setreg()|
-      • {inclusive}  (boolean) indicating whether column of pos2 is inclusive
+      • {bufnr}      (integer) Buffer number, or 0 for current buffer
+      • {pos1}       integer[]|string Start of region as a (line, column)
+                     tuple or |getpos()|-compatible string
+      • {pos2}       integer[]|string End of region as a (line, column) tuple
+                     or |getpos()|-compatible string
+      • {regtype}    (string) |setreg()|-style selection type
+      • {inclusive}  (boolean) Controls whether `pos2` column is inclusive
+                     (see also 'selection').
 
     Return: ~
-        (table) region Table of the form `{linenr = {startcol,endcol}}`.
-        `endcol` is exclusive, and whole lines are marked with
+        (table) region Dict of the form `{linenr = {startcol,endcol}}`.
+        `endcol` is exclusive, and whole lines are returned as
         `{startcol,endcol} = {0,-1}`.
 
 schedule_wrap({cb})                                      *vim.schedule_wrap()*
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 6ffd45d013..68ebb8cc94 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -536,12 +536,14 @@ Working directory (Vim implemented some of these after Nvim):
   working directory. Use `getcwd(-1, -1)` to get the global working directory.
 
 ==============================================================================
-Missing legacy features					 *nvim-missing*
+Missing features					 *nvim-missing*
 
 These legacy Vim features are not yet implemented:
 
-*:gui*
-*:gvim*
+- *:gui*
+- *:gvim*
+- *'completepopup'*
+- *'previewpopup'*
 
 ==============================================================================
 Removed legacy features					 *nvim-removed*
@@ -644,6 +646,7 @@ Options:
   'highlight' (Names of builtin |highlight-groups| cannot be changed.)
   *'hkmap'* *'hk'* use `set keymap=hebrew` instead.
   *'hkmapp'* *'hkp'* use `set keymap=hebrewp` instead.
+  keyprotocol
 
   *'pastetoggle'* *'pt'* Just Paste It.™ |paste| is handled automatically when
   you paste text using your terminal's or GUI's paste feature (CTRL-SHIFT-v,
@@ -687,6 +690,7 @@ Options:
     Use |g8| or |ga|.  See |mbyte-combining|.
   *'maxmem'* Nvim delegates memory-management to the OS.
   *'maxmemtot'* Nvim delegates memory-management to the OS.
+  printoptions
   *'printdevice'*
   *'printencoding'*
   *'printexpr'*
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 6f701e9ae9..80e7518b01 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -460,17 +460,18 @@ do
   vim.t = make_dict_accessor('t')
 end
 
---- Get a table of lines with start, end columns for a region marked by two points.
---- Input and output positions are (0,0)-indexed and indicate byte positions.
+--- Gets a dict of line segment ("chunk") positions for the region from `pos1` to `pos2`.
 ---
----@param bufnr integer number of buffer
----@param pos1 integer[]|string start of region as a (line, column) tuple or string accepted by |getpos()|
----@param pos2 integer[]|string end of region as a (line, column) tuple or string accepted by |getpos()|
----@param regtype string type of selection, see |setreg()|
----@param inclusive boolean indicating whether column of pos2 is inclusive
----@return table region Table of the form `{linenr = {startcol,endcol}}`.
----        `endcol` is exclusive, and whole lines are marked with
----        `{startcol,endcol} = {0,-1}`.
+--- Input and output positions are byte positions, (0,0)-indexed. "End of line" column
+--- position (for example, |linewise| visual selection) is returned as |v:maxcol| (big number).
+---
+---@param bufnr integer Buffer number, or 0 for current buffer
+---@param pos1 integer[]|string Start of region as a (line, column) tuple or |getpos()|-compatible string
+---@param pos2 integer[]|string End of region as a (line, column) tuple or |getpos()|-compatible string
+---@param regtype string \|setreg()|-style selection type
+---@param inclusive boolean Controls whether `pos2` column is inclusive (see also 'selection').
+---@return table region Dict of the form `{linenr = {startcol,endcol}}`. `endcol` is exclusive, and
+---whole lines are returned as `{startcol,endcol} = {0,-1}`.
 function vim.region(bufnr, pos1, pos2, regtype, inclusive)
   if not vim.api.nvim_buf_is_loaded(bufnr) then
     vim.fn.bufload(bufnr)
@@ -610,18 +611,17 @@ local on_key_cbs = {}
 --- The Nvim command-line option |-w| is related but does not support callbacks
 --- and cannot be toggled dynamically.
 ---
----@param fn function: Callback function. It should take one string argument.
----                   On each key press, Nvim passes the key char to fn(). |i_CTRL-V|
----                   If {fn} is nil, it removes the callback for the associated {ns_id}
+---@note {fn} will be removed on error.
+---@note {fn} will not be cleared by |nvim_buf_clear_namespace()|
+---@note {fn} will receive the keys after mappings have been evaluated
+---
+---@param fn fun(key: string) Function invoked on every key press. |i_CTRL-V|
+---                   Returning nil removes the callback associated with namespace {ns_id}.
 ---@param ns_id integer? Namespace ID. If nil or 0, generates and returns a new
 ---                    |nvim_create_namespace()| id.
 ---
 ---@return integer Namespace id associated with {fn}. Or count of all callbacks
 ---if on_key() is called without arguments.
----
----@note {fn} will be removed if an error occurs while calling.
----@note {fn} will not be cleared by |nvim_buf_clear_namespace()|
----@note {fn} will receive the keys after mappings have been evaluated
 function vim.on_key(fn, ns_id)
   if fn == nil and ns_id == nil then
     return #on_key_cbs
@@ -1049,10 +1049,10 @@ function vim._init_default_mappings()
   map('i', '<C-W>', '<C-G>u<C-W>')
   vim.keymap.set('x', '*', function()
     _visual_search('/')
-  end, { desc = 'Nvim builtin', silent = true })
+  end, { desc = ':help v_star-default', silent = true })
   vim.keymap.set('x', '#', function()
     _visual_search('?')
-  end, { desc = 'Nvim builtin', silent = true })
+  end, { desc = ':help v_#-default', silent = true })
   -- Use : instead of <Cmd> so that ranges are supported. #19365
   map('n', '&', ':&&<CR>')
 
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 02b97b0ae1..a0322556b4 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -1192,8 +1192,9 @@ Boolean nvim_buf_set_mark(Buffer buffer, String name, Integer line, Integer col,
   return res;
 }
 
-/// Returns a tuple (row,col) representing the position of the named mark. See
-/// |mark-motions|.
+/// Returns a `(row,col)` tuple representing the position of the named mark.
+/// "End of line" column position is returned as |v:maxcol| (big number).
+/// See |mark-motions|.
 ///
 /// Marks are (1,0)-indexed. |api-indexing|
 ///
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 8c40e5ccd7..3ffaaab780 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1980,12 +1980,13 @@ Boolean nvim_del_mark(String name, Error *err)
   return res;
 }
 
-/// Return a tuple (row, col, buffer, buffername) representing the position of
-/// the uppercase/file named mark. See |mark-motions|.
+/// Returns a `(row, col, buffer, buffername)` tuple representing the position
+/// of the uppercase/file named mark. "End of line" column position is returned
+/// as |v:maxcol| (big number). See |mark-motions|.
 ///
 /// Marks are (1,0)-indexed. |api-indexing|
 ///
-/// @note fails with error if a lowercase or buffer local named mark is used.
+/// @note Lowercase name (or other buffer-local mark) is an error.
 /// @param name       Mark name
 /// @param opts       Optional parameters. Reserved for future use.
 /// @return 4-tuple (row, col, buffer, buffername), (0, 0, 0, '') if the mark is