Merge #24295 from justinmk/doc2

docs: "Return (multiple)", condense @notes

6 files changed, 82 insertions, 82 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 46c5f2ea18..d96169066c 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -727,8 +727,8 @@ nvim_del_keymap({mode}, {lhs})                             *nvim_del_keymap()*
 nvim_del_mark({name})                                        *nvim_del_mark()*
     Deletes an uppercase/file named mark. See |mark-motions|.
 
-    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.
 
     Parameters: ~
       • {name}  Mark name
@@ -952,6 +952,10 @@ nvim_get_current_win()                                *nvim_get_current_win()*
 nvim_get_hl({ns_id}, {*opts})                                  *nvim_get_hl()*
     Gets all or specific highlight groups in a namespace.
 
+    Note: ~
+      • When the `link` attribute is defined in the highlight definition map,
+        other attributes will not be taking effect (see |:hi-link|).
+
     Parameters: ~
       • {ns_id}  Get highlight groups for namespace ns_id
                  |nvim_get_namespaces()|. Use 0 to get global highlight groups
@@ -967,10 +971,6 @@ nvim_get_hl({ns_id}, {*opts})                                  *nvim_get_hl()*
         map as in |nvim_set_hl()|, or only a single highlight definition map
         if requested by name or id.
 
-    Note:
-        When the `link` attribute is defined in the highlight definition map,
-        other attributes will not be taking effect (see |:hi-link|).
-
 nvim_get_hl_id_by_name({name})                      *nvim_get_hl_id_by_name()*
     Gets a highlight group by name
 
@@ -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.
+    Note: ~
+      • Lowercase name (or other buffer-local mark) is an error.
 
     Parameters: ~
       • {name}  Mark name
@@ -1074,12 +1075,10 @@ nvim_input({keys})                                              *nvim_input()*
 
     On execution error: does not fail, but updates v:errmsg.
 
-    Note:
-        |keycodes| like <CR> are translated, so "<" is special. To input a
+    Note: ~
+      • |keycodes| like <CR> are translated, so "<" is special. To input a
         literal "<", send <LT>.
-
-    Note:
-        For mouse events use |nvim_input_mouse()|. The pseudokey form
+      • For mouse events use |nvim_input_mouse()|. The pseudokey form
         "<LeftMouse><col,row>" is deprecated since |api-level| 6.
 
     Attributes: ~
@@ -1099,8 +1098,8 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
     Non-blocking: does not wait on any result, but queues the event to be
     processed soon by the event loop.
 
-    Note:
-        Currently this doesn't support "scripting" multiple mouse events by
+    Note: ~
+      • Currently this doesn't support "scripting" multiple mouse events by
         calling it multiple times in a loop: the intermediate mouse positions
         will be ignored. It should be used to implement real-time mouse input
         in a GUI. The deprecated pseudokey form ("<LeftMouse><col,row>") of
@@ -1316,8 +1315,8 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
     appropriate. Example: library first identifies the channel, then a plugin
     using that library later identifies itself.
 
-    Note:
-        "Something is better than nothing". You don't need to include all the
+    Note: ~
+      • "Something is better than nothing". You don't need to include all the
         fields.
 
     Attributes: ~
@@ -1409,21 +1408,17 @@ nvim_set_current_win({window})                        *nvim_set_current_win()*
 nvim_set_hl({ns_id}, {name}, {*val})                           *nvim_set_hl()*
     Sets a highlight group.
 
-    Note:
-        Unlike the `:highlight` command which can update a highlight group,
-        this function completely replaces the definition. For example:
+    Note: ~
+      • Unlike the `:highlight` command which can update a highlight group, this
+        function completely replaces the definition. For example:
         `nvim_set_hl(0, 'Visual', {})` will clear the highlight group
         'Visual'.
-
-    Note:
-        The fg and bg keys also accept the string values `"fg"` or `"bg"`
-        which act as aliases to the corresponding foreground and background
-        values of the Normal group. If the Normal group has not been defined,
-        using these values results in an error.
-
-    Note:
-        If `link` is used in combination with other attributes; only the
-        `link` will take effect (see |:hi-link|).
+      • The fg and bg keys also accept the string values `"fg"` or `"bg"` which
+        act as aliases to the corresponding foreground and background values
+        of the Normal group. If the Normal group has not been defined, using
+        these values results in an error.
+      • If `link` is used in combination with other attributes; only the `link`
+        will take effect (see |:hi-link|).
 
     Parameters: ~
       • {ns_id}  Namespace id for this highlight |nvim_create_namespace()|.
@@ -2140,8 +2135,8 @@ nvim_buf_del_keymap({buffer}, {mode}, {lhs})           *nvim_buf_del_keymap()*
 nvim_buf_del_mark({buffer}, {name})                      *nvim_buf_del_mark()*
     Deletes a named mark in the buffer. See |mark-motions|.
 
-    Note:
-        only deletes marks set in the buffer, if the mark is not set in the
+    Note: ~
+      • only deletes marks set in the buffer, if the mark is not set in the
         buffer it will return false.
 
     Parameters: ~
@@ -2232,7 +2227,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|
@@ -2323,8 +2319,8 @@ nvim_buf_is_loaded({buffer})                            *nvim_buf_is_loaded()*
 nvim_buf_is_valid({buffer})                              *nvim_buf_is_valid()*
     Checks if a buffer is valid.
 
-    Note:
-        Even if a buffer is valid it may have been unloaded. See |api-buffer|
+    Note: ~
+      • Even if a buffer is valid it may have been unloaded. See |api-buffer|
         for more info about unloaded buffers.
 
     Parameters: ~
@@ -2386,8 +2382,8 @@ nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts})
 
     Marks are (1,0)-indexed. |api-indexing|
 
-    Note:
-        Passing 0 as line deletes the mark
+    Note: ~
+      • Passing 0 as line deletes the mark
 
     Parameters: ~
       • {buffer}  Buffer to set the mark on
@@ -3442,8 +3438,8 @@ nvim_ui_attach({width}, {height}, {options})                *nvim_ui_attach()*
     Implies that the client is ready to show the UI. Adds the client to the
     list of UIs. |nvim_list_uis()|
 
-    Note:
-        If multiple UI clients are attached, the global screen dimensions
+    Note: ~
+      • If multiple UI clients are attached, the global screen dimensions
         degrade to the smallest client. E.g. if client A requests 80x40 but
         client B requests 200x100, the global screen has size 80x40.
 
diff --git a/runtime/doc/diagnostic.txt b/runtime/doc/diagnostic.txt
index 9dd42061ef..4b2b5e5f9a 100644
--- a/runtime/doc/diagnostic.txt
+++ b/runtime/doc/diagnostic.txt
@@ -361,8 +361,8 @@ config({opts}, {namespace})                          *vim.diagnostic.config()*
 
     then virtual text will not be enabled for those diagnostics.
 
-    Note:
-        Each of the configuration options below accepts one of the following:
+    Note: ~
+      • Each of the configuration options below accepts one of the following:
         • `false`: Disable this feature
         • `true`: Enable this feature, use default settings.
         • `table`: Enable this feature with overrides. Use an empty table to
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index b21c1d6e9d..7bec93de89 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -680,7 +680,7 @@ buf_request_sync({bufnr}, {method}, {params}, {timeout_ms})
       • {timeout_ms}  (integer|nil) Maximum time in milliseconds to wait for a
                       result. Defaults to 1000
 
-    Return: ~
+    Return (multiple): ~
         (table) result Map of client_id:request_result.
         (string|nil) err On timeout, cancel, or error, `err` is a string
         describing the failure reason, and `result` is nil.
@@ -1126,8 +1126,9 @@ completion({context})                               *vim.lsp.buf.completion()*
 
 declaration({options})                             *vim.lsp.buf.declaration()*
     Jumps to the declaration of the symbol under the cursor.
-    Note:
-        Many servers do not implement this method. Generally, see
+
+    Note: ~
+      • Many servers do not implement this method. Generally, see
         |vim.lsp.buf.definition()| instead.
 
     Parameters: ~
@@ -1623,7 +1624,7 @@ convert_signature_help_to_markdown_lines({signature_help}, {ft}, {triggers})
       • {triggers}        (table|nil) list of trigger characters from the lsp
                           server. used to better determine parameter offsets
 
-    Return: ~
+    Return (multiple): ~
         (table|nil) table list of lines of converted markdown.
         (table|nil) table of active hl
 
@@ -1833,7 +1834,7 @@ open_floating_preview({contents}, {syntax}, {opts})
                       {focusable} is also `true`, focus an existing floating
                       window with the same {focus_id}
 
-    Return: ~
+    Return (multiple): ~
         (integer) bufnr of newly created float window
         (integer) winid of newly created float window preview window
 
@@ -1857,7 +1858,7 @@ preview_location({location}, {opts})         *vim.lsp.util.preview_location()*
     Parameters: ~
       • {location}  (table) a single `Location` or `LocationLink`
 
-    Return: ~
+    Return (multiple): ~
         (integer|nil) buffer id of float window
         (integer|nil) window id of float window
 
@@ -2091,7 +2092,7 @@ start({cmd}, {cmd_args}, {dispatchers}, {extra_spawn_params})
                               • {env} (table) Additional environment variables
                                 for LSP server process
 
-    Return: ~
+    Return (multiple): ~
         Client RPC object.
         Methods:
         • `notify()` |vim.lsp.rpc.notify()|
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 63523c32d5..9e4815bea5 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1475,17 +1475,15 @@ on_key({fn}, {ns_id})                                           *vim.on_key()*
     The Nvim command-line option |-w| is related but does not support
     callbacks and cannot be toggled dynamically.
 
-    Note:
-        {fn} will not be cleared by |nvim_buf_clear_namespace()|
-
-    Note:
-        {fn} will receive the keys after mappings have been evaluated
+    Note: ~
+      • {fn} will be removed on error.
+      • {fn} will not be cleared by |nvim_buf_clear_namespace()|
+      • {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 +1491,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 +1538,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()*
@@ -2361,7 +2360,7 @@ open({path})                                                   *vim.ui.open()*
     Parameters: ~
       • {path}  (string) Path or URL to open
 
-    Return: ~
+    Return (multiple): ~
         SystemCompleted|nil # Command result, or nil if not found.
         (string|nil) # Error message on failure
 
@@ -2564,7 +2563,7 @@ match({args})                                           *vim.filetype.match()*
                   contents to use for matching. Can be used with {filename}.
                   Mutually exclusive with {buf}.
 
-    Return: ~
+    Return (multiple): ~
         (string|nil) If a match was found, the matched filetype.
         (function|nil) A function that modifies buffer state when called (for
         example, to set some filetype specific buffer variables). The function
@@ -2909,8 +2908,8 @@ cmp({v1}, {v2})                                            *vim.version.cmp()*
        end
 <
 
-    Note:
-        Per semver, build metadata is ignored when comparing two
+    Note: ~
+      • Per semver, build metadata is ignored when comparing two
         otherwise-equivalent versions.
 
     Parameters: ~
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 7539417197..070659ce3d 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -617,7 +617,7 @@ get_node_range({node_or_range})              *vim.treesitter.get_node_range()*
     Parameters: ~
       • {node_or_range}  (|TSNode| | table) Node or table of positions
 
-    Return: ~
+    Return (multiple): ~
         (integer) start_row
         (integer) start_col
         (integer) end_row
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'*