Merge remote-tracking branch 'upstream/master' into userreguserreg

1 files changed, 440 insertions, 307 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 0e1cc3c28c..ba3b7c0915 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -7,7 +7,7 @@
 Nvim API                                                           *API* *api*
 
 Nvim exposes a powerful API that can be used by plugins and external processes
-via |RPC|, |Lua| and VimL (|eval-api|).
+via |RPC|, |Lua| and Vimscript (|eval-api|).
 
 Applications can also embed libnvim to work with the C API directly.
 
@@ -17,8 +17,15 @@ Applications can also embed libnvim to work with the C API directly.
 API Usage                                               *api-rpc* *RPC* *rpc*
 
                                                         *msgpack-rpc*
-RPC is the typical way to control Nvim programmatically.  Nvim implements the
-MessagePack-RPC protocol:
+RPC is the main way to control Nvim programmatically.  Nvim implements the
+MessagePack-RPC protocol with these extra (out-of-spec) constraints:
+
+1. Responses must be given in reverse order of requests (like "unwinding
+   a stack").
+2. Nvim processes all messages (requests and notifications) in the order they
+   are received.
+
+MessagePack-RPC specification:
   https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md
   https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md
 
@@ -202,7 +209,7 @@ any of these approaches:
      nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)'
 <
   3. Use the |api_info()| Vimscript function. >vim
-     :lua print(vim.inspect(vim.fn.api_info()))
+     :lua vim.print(vim.fn.api_info())
 <     Example using |filter()| to exclude non-deprecated API functions: >vim
      :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
 
@@ -273,7 +280,7 @@ nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata},
     changed but not the buffer contents. {linedata} contains the changed
     screen lines. This happens when 'inccommand' shows a buffer preview.
 
-    Properties:~
+    Properties: ~
         {buf} API buffer handle (buffer number)
 
         {changedtick} value of |b:changedtick| for the buffer. If you send an
@@ -306,7 +313,7 @@ nvim_buf_changedtick_event[{buf}, {changedtick}]  *nvim_buf_changedtick_event*
     When |b:changedtick| was incremented but no text was changed. Relevant for
     undo/redo.
 
-    Properties:~
+    Properties: ~
         {buf} API buffer handle (buffer number)
         {changedtick} new value of |b:changedtick| for the buffer
 
@@ -319,7 +326,7 @@ nvim_buf_detach_event[{buf}]                           *nvim_buf_detach_event*
       |:checktime| or 'autoread'.
     - Generally: whenever the buffer contents are unloaded from memory.
 
-    Properties:~
+    Properties: ~
         {buf} API buffer handle (buffer number)
 
 
@@ -356,6 +363,7 @@ In-process Lua plugins can receive buffer updates in the form of Lua
 callbacks. These callbacks are called frequently in various contexts;
 |textlock| prevents changing buffer contents and window layout (use
 |vim.schedule()| to defer such operations to the main loop instead).
+Moving the cursor is allowed, but it is restored afterwards.
 
 |nvim_buf_attach()| will take keyword args for the callbacks. "on_lines" will
 receive parameters ("lines", {buf}, {changedtick}, {firstline}, {lastline},
@@ -399,6 +407,23 @@ external highlighter plugin wants to add many highlights in a batch,
 performance can be improved by calling |nvim_buf_add_highlight()| as an
 asynchronous notification, after first (synchronously) requesting a source id.
 
+|nvim_buf_add_highlight()| adds highlights as |extmarks|. If highlights need to
+be tracked or manipulated after adding them, it is better to use
+|nvim_buf_set_extmark()| directly, as this function returns the placed |extmark|
+id. Thus, instead of >lua
+  vim.api.nvim_buf_add_highlight(buf, ns_id, hl_group, line, col_start, col_end)
+<
+use >lua
+  -- create the highlight through an extmark
+  extid = vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = hl_group})
+
+  -- example: modify the extmark's highlight group
+  vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid})
+
+  -- example: change the highlight's position
+  vim.api.nvim_buf_set_extmark(buf, ns_id, NEW_LINE, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid})
+<
+
 Example using the Python API client (|pynvim|):
 >python
     src = vim.new_highlight_source()
@@ -451,6 +476,11 @@ Buffer text can be highlighted by typical mechanisms (syntax highlighting,
 options from the current window; specify `style=minimal` in |nvim_open_win()|
 to disable various visual features such as the 'number' column.
 
+Other highlight groups specific to floating windows:
+- |hl-FloatBorder| for window's border
+- |hl-FloatTitle| for window's title
+- |hl-FloatFooter| for window's footer
+
 Currently, floating windows don't support some widgets like scrollbar.
 
 The output of |:mksession| does not include commands for restoring floating
@@ -464,7 +494,7 @@ Example: create a float with scratch buffer: >vim
         \ 'row': 1, 'anchor': 'NW', 'style': 'minimal'}
     let win = nvim_open_win(buf, 0, opts)
     " optional: change highlight, otherwise Pmenu is used
-    call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight')
+    call nvim_set_option_value('winhl', 'Normal:MyHighlight', {'win': win})
 <
 
 ==============================================================================
@@ -558,7 +588,7 @@ nvim__get_runtime({pat}, {all}, {*opts})                 *nvim__get_runtime()*
     Parameters: ~
       • {pat}   pattern of files to search for
       • {all}   whether to return all matches or only the first
-      • {opts}  is_lua: only search lua subdirs
+      • {opts}  is_lua: only search Lua subdirs
 
     Return: ~
         list of absolute paths to the found files
@@ -615,6 +645,10 @@ nvim__inspect_cell({grid}, {row}, {col})                *nvim__inspect_cell()*
     NB: if your UI doesn't use hlstate, this will not return hlstate first
     time.
 
+nvim__invalidate_glyph_cache()                *nvim__invalidate_glyph_cache()*
+    For testing. The condition in schar_cache_clear_if_full is hard to reach,
+    so this function can be used to force a cache clear in a test.
+
 nvim__stats()                                                  *nvim__stats()*
     Gets internal stats.
 
@@ -679,7 +713,7 @@ nvim_create_buf({listed}, {scratch})                       *nvim_create_buf()*
         Buffer handle, or 0 on error
 
     See also: ~
-        buf_open_scratch
+      • buf_open_scratch
 
 nvim_del_current_line()                              *nvim_del_current_line()*
     Deletes the current line.
@@ -693,13 +727,13 @@ nvim_del_keymap({mode}, {lhs})                             *nvim_del_keymap()*
     To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|.
 
     See also: ~
-        |nvim_set_keymap()|
+      • |nvim_set_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
@@ -708,8 +742,8 @@ nvim_del_mark({name})                                        *nvim_del_mark()*
         true if the mark was deleted, else false.
 
     See also: ~
-        |nvim_buf_del_mark()|
-        |nvim_get_mark()|
+      • |nvim_buf_del_mark()|
+      • |nvim_get_mark()|
 
 nvim_del_var({name})                                          *nvim_del_var()*
     Removes a global (g:) variable.
@@ -746,7 +780,7 @@ nvim_err_writeln({str})                                   *nvim_err_writeln()*
       • {str}  Message
 
     See also: ~
-        nvim_err_write()
+      • nvim_err_write()
 
 nvim_eval_statusline({str}, {*opts})                  *nvim_eval_statusline()*
     Evaluates statusline string.
@@ -768,6 +802,8 @@ nvim_eval_statusline({str}, {*opts})                  *nvim_eval_statusline()*
                 • use_tabline: (boolean) Evaluate tabline instead of
                   statusline. When true, {winid} is ignored. Mutually
                   exclusive with {use_winbar}.
+                • use_statuscol_lnum: (number) Evaluate statuscolumn for this
+                  line number instead of statusline.
 
     Return: ~
         Dictionary containing statusline information, with these keys:
@@ -820,8 +856,8 @@ nvim_feedkeys({keys}, {mode}, {escape_ks})                   *nvim_feedkeys()*
                      true otherwise.
 
     See also: ~
-        feedkeys()
-        vim_strsave_escape_ks
+      • feedkeys()
+      • vim_strsave_escape_ks
 
 nvim_get_api_info()                                      *nvim_get_api_info()*
     Returns a 2-tuple (Array), where item 0 is the current channel id and item
@@ -918,37 +954,48 @@ nvim_get_current_win()                                *nvim_get_current_win()*
     Return: ~
         Window handle
 
-nvim_get_hl_by_id({hl_id}, {rgb})                        *nvim_get_hl_by_id()*
-    Gets a highlight definition by id. |hlID()|
-
-    Parameters: ~
-      • {hl_id}  Highlight id as returned by |hlID()|
-      • {rgb}    Export RGB colors
-
-    Return: ~
-        Highlight definition map
-
-    See also: ~
-        nvim_get_hl_by_name
+nvim_get_hl({ns_id}, {*opts})                                  *nvim_get_hl()*
+    Gets all or specific highlight groups in a namespace.
 
-nvim_get_hl_by_name({name}, {rgb})                     *nvim_get_hl_by_name()*
-    Gets a highlight definition by name.
+    Note: ~
+      • When the `link` attribute is defined in the highlight definition map,
+        other attributes will not be taking effect (see |:hi-link|).
 
     Parameters: ~
-      • {name}  Highlight group name
-      • {rgb}   Export RGB colors
+      • {ns_id}  Get highlight groups for namespace ns_id
+                 |nvim_get_namespaces()|. Use 0 to get global highlight groups
+                 |:highlight|.
+      • {opts}   Options dict:
+                 • name: (string) Get a highlight definition by name.
+                 • id: (integer) Get a highlight definition by id.
+                 • link: (boolean, default true) Show linked group name
+                   instead of effective definition |:hi-link|.
+                 • create: (boolean, default true) When highlight group
+                   doesn't exist create it.
 
     Return: ~
-        Highlight definition map
-
-    See also: ~
-        nvim_get_hl_by_id
+        Highlight groups as a map from group name to a highlight definition
+        map as in |nvim_set_hl()|, or only a single highlight definition map
+        if requested by name or id.
 
 nvim_get_hl_id_by_name({name})                      *nvim_get_hl_id_by_name()*
     Gets a highlight group by name
 
     similar to |hlID()|, but allocates a new ID if not present.
 
+nvim_get_hl_ns({*opts})                                     *nvim_get_hl_ns()*
+    Gets the active highlight namespace.
+
+    Parameters: ~
+      • {opts}  Optional parameters
+                • winid: (number) |window-ID| for retrieving a window's
+                  highlight namespace. A value of -1 is returned when
+                  |nvim_win_set_hl_ns()| has not been called for the window
+                  (or was called with a namespace of -1).
+
+    Return: ~
+        Namespace id, or -1
+
 nvim_get_keymap({mode})                                    *nvim_get_keymap()*
     Gets a list of global (non-buffer-local) |mapping| definitions.
 
@@ -960,13 +1007,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
@@ -977,8 +1025,8 @@ nvim_get_mark({name}, {opts})                                *nvim_get_mark()*
         not set.
 
     See also: ~
-        |nvim_buf_set_mark()|
-        |nvim_del_mark()|
+      • |nvim_buf_set_mark()|
+      • |nvim_del_mark()|
 
 nvim_get_mode()                                              *nvim_get_mode()*
     Gets the current mode. |mode()| "blocking" is true if Nvim is waiting for
@@ -1047,12 +1095,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: ~
@@ -1072,8 +1118,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
@@ -1113,7 +1159,7 @@ nvim_list_chans()                                          *nvim_list_chans()*
         specified at |nvim_get_chan_info()|.
 
 nvim_list_runtime_paths()                          *nvim_list_runtime_paths()*
-    Gets the paths contained in 'runtimepath'.
+    Gets the paths contained in |runtime-search-path|.
 
     Return: ~
         List of paths
@@ -1173,10 +1219,13 @@ nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
     |nvim_chan_send()| can be called immediately to process sequences in a
     virtual terminal having the intended size.
 
+    Attributes: ~
+        not allowed when |textlock| is active
+
     Parameters: ~
       • {buffer}  the buffer to use (expected to be empty)
       • {opts}    Optional parameters.
-                  • on_input: lua callback for input sent, i e keypresses in
+                  • on_input: Lua callback for input sent, i e keypresses in
                     terminal mode. Note: keypresses are sent raw as they would
                     be to the pty master end. For instance, a carriage return
                     is sent as a "\r", not as a "\n". |textlock| applies. It
@@ -1252,8 +1301,8 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
       • {special}    Replace |keycodes|, e.g. <CR> becomes a "\r" char.
 
     See also: ~
-        replace_termcodes
-        cpoptions
+      • replace_termcodes
+      • cpoptions
 
                                                 *nvim_select_popupmenu_item()*
 nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
@@ -1286,8 +1335,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: ~
@@ -1307,7 +1356,11 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
       • {type}        Must be one of the following values. Client libraries
                       should default to "remote" unless overridden by the
                       user.
-                      • "remote" remote client connected to Nvim.
+                      • "remote" remote client connected "Nvim flavored"
+                        MessagePack-RPC (responses must be in reverse order of
+                        requests). |msgpack-rpc|
+                      • "msgpack-rpc" remote client connected to Nvim via
+                        fully MessagePack-RPC compliant protocol.
                       • "ui" gui frontend
                       • "embedder" application using Nvim as a component (for
                         example, IDE/editor implementing a vim mode).
@@ -1338,7 +1391,7 @@ nvim_set_current_buf({buffer})                        *nvim_set_current_buf()*
     Sets the current buffer.
 
     Attributes: ~
-        not allowed when |textlock| is active
+        not allowed when |textlock| is active or in the |cmdwin|
 
     Parameters: ~
       • {buffer}  Buffer handle
@@ -1362,7 +1415,7 @@ nvim_set_current_tabpage({tabpage})               *nvim_set_current_tabpage()*
     Sets the current tabpage.
 
     Attributes: ~
-        not allowed when |textlock| is active
+        not allowed when |textlock| is active or in the |cmdwin|
 
     Parameters: ~
       • {tabpage}  Tabpage handle
@@ -1371,7 +1424,7 @@ nvim_set_current_win({window})                        *nvim_set_current_win()*
     Sets the current window.
 
     Attributes: ~
-        not allowed when |textlock| is active
+        not allowed when |textlock| is active or in the |cmdwin|
 
     Parameters: ~
       • {window}  Window handle
@@ -1379,21 +1432,24 @@ 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.
+      • 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()|.
                  Use 0 to set a highlight group globally |:highlight|.
+                 Highlights from non-global namespaces are not active by
+                 default, use |nvim_set_hl_ns()| or |nvim_win_set_hl_ns()| to
+                 activate them.
       • {name}   Highlight group name, e.g. "ErrorMsg"
       • {val}    Highlight definition map, accepts the following keys:
                  • fg (or foreground): color name or "#RRGGBB", see note.
@@ -1419,16 +1475,19 @@ nvim_set_hl({ns_id}, {name}, {*val})                           *nvim_set_hl()*
                  • cterm: cterm attribute map, like |highlight-args|. If not
                    set, cterm attributes will match those from the attribute
                    map documented above.
+                 • force: if true force update the highlight group when it
+                   exists.
 
 nvim_set_hl_ns({ns_id})                                     *nvim_set_hl_ns()*
-    Set active namespace for highlights. This can be set for a single window,
-    see |nvim_win_set_hl_ns()|.
+    Set active namespace for highlights defined with |nvim_set_hl()|. This can
+    be set for a single window, see |nvim_win_set_hl_ns()|.
 
     Parameters: ~
       • {ns_id}  the namespace to use
 
 nvim_set_hl_ns_fast({ns_id})                           *nvim_set_hl_ns_fast()*
-    Set active namespace for highlights while redrawing.
+    Set active namespace for highlights defined with |nvim_set_hl()| while
+    redrawing.
 
     This function meant to be called while redrawing, primarily from
     |nvim_set_decoration_provider()| on_win and on_line callbacks, which are
@@ -1458,19 +1517,20 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
 
     Parameters: ~
       • {mode}  Mode short-name (map command prefix: "n", "i", "v", "x", …) or
-                "!" for |:map!|, or empty string for |:map|.
+                "!" for |:map!|, or empty string for |:map|. "ia", "ca" or
+                "!a" for abbreviation in Insert mode, Cmdline mode, or both,
+                respectively
       • {lhs}   Left-hand-side |{lhs}| of the mapping.
       • {rhs}   Right-hand-side |{rhs}| of the mapping.
-      • {opts}  Optional parameters map: keys are |:map-arguments|, values are
-                booleans (default false). Accepts all |:map-arguments| as keys
-                excluding |<buffer>| but including |:noremap| and "desc".
-                Unknown key is an error. "desc" can be used to give a
-                description to the mapping. When called from Lua, also accepts
-                a "callback" key that takes a Lua function to call when the
-                mapping is executed. When "expr" is true, "replace_keycodes"
-                (boolean) can be used to replace keycodes in the resulting
-                string (see |nvim_replace_termcodes()|), and a Lua callback
-                returning `nil` is equivalent to returning an empty string.
+      • {opts}  Optional parameters map: Accepts all |:map-arguments| as keys
+                except |<buffer>|, values are booleans (default false). Also:
+                • "noremap" disables |recursive_mapping|, like |:noremap|
+                • "desc" human-readable description.
+                • "callback" Lua function called in place of {rhs}.
+                • "replace_keycodes" (boolean) When "expr" is true, replace
+                  keycodes in the resulting string (see
+                  |nvim_replace_termcodes()|). Returning nil from the Lua
+                  "callback" is equivalent to returning an empty string.
 
 nvim_set_var({name}, {value})                                 *nvim_set_var()*
     Sets a global (g:) variable.
@@ -1520,22 +1580,22 @@ Vimscript Functions                                            *api-vimscript*
 
                                                    *nvim_call_dict_function()*
 nvim_call_dict_function({dict}, {fn}, {args})
-    Calls a VimL |Dictionary-function| with the given arguments.
+    Calls a Vimscript |Dictionary-function| with the given arguments.
 
-    On execution error: fails with VimL error, updates v:errmsg.
+    On execution error: fails with Vimscript error, updates v:errmsg.
 
     Parameters: ~
-      • {dict}  Dictionary, or String evaluating to a VimL |self| dict
-      • {fn}    Name of the function defined on the VimL dict
+      • {dict}  Dictionary, or String evaluating to a Vimscript |self| dict
+      • {fn}    Name of the function defined on the Vimscript dict
       • {args}  Function arguments packed in an Array
 
     Return: ~
         Result of the function call
 
 nvim_call_function({fn}, {args})                        *nvim_call_function()*
-    Calls a VimL function with the given arguments.
+    Calls a Vimscript function with the given arguments.
 
-    On execution error: fails with VimL error, updates v:errmsg.
+    On execution error: fails with Vimscript error, updates v:errmsg.
 
     Parameters: ~
       • {fn}    Function to call
@@ -1547,54 +1607,56 @@ nvim_call_function({fn}, {args})                        *nvim_call_function()*
 nvim_command({command})                                       *nvim_command()*
     Executes an Ex command.
 
-    On execution error: fails with VimL error, updates v:errmsg.
+    On execution error: fails with Vimscript error, updates v:errmsg.
 
-    Prefer using |nvim_cmd()| or |nvim_exec()| over this. To evaluate multiple
-    lines of Vim script or an Ex command directly, use |nvim_exec()|. To
-    construct an Ex command using a structured format and then execute it, use
-    |nvim_cmd()|. To modify an Ex command before evaluating it, use
-    |nvim_parse_cmd()| in conjunction with |nvim_cmd()|.
+    Prefer using |nvim_cmd()| or |nvim_exec2()| over this. To evaluate
+    multiple lines of Vim script or an Ex command directly, use
+    |nvim_exec2()|. To construct an Ex command using a structured format and
+    then execute it, use |nvim_cmd()|. To modify an Ex command before
+    evaluating it, use |nvim_parse_cmd()| in conjunction with |nvim_cmd()|.
 
     Parameters: ~
       • {command}  Ex command string
 
 nvim_eval({expr})                                                *nvim_eval()*
-    Evaluates a VimL |expression|. Dictionaries and Lists are recursively
+    Evaluates a Vimscript |expression|. Dictionaries and Lists are recursively
     expanded.
 
-    On execution error: fails with VimL error, updates v:errmsg.
+    On execution error: fails with Vimscript error, updates v:errmsg.
 
     Parameters: ~
-      • {expr}  VimL expression string
+      • {expr}  Vimscript expression string
 
     Return: ~
         Evaluation result or expanded object
 
-nvim_exec({src}, {output})                                       *nvim_exec()*
+nvim_exec2({src}, {*opts})                                      *nvim_exec2()*
     Executes Vimscript (multiline block of Ex commands), like anonymous
     |:source|.
 
     Unlike |nvim_command()| this function supports heredocs, script-scope
     (s:), etc.
 
-    On execution error: fails with VimL error, updates v:errmsg.
+    On execution error: fails with Vimscript error, updates v:errmsg.
 
     Parameters: ~
-      • {src}     Vimscript code
-      • {output}  Capture and return all (non-error, non-shell |:!|) output
+      • {src}   Vimscript code
+      • {opts}  Optional parameters.
+                • output: (boolean, default false) Whether to capture and
+                  return all (non-error, non-shell |:!|) output.
 
     Return: ~
-        Output (non-error, non-shell |:!|) if `output` is true, else empty
-        string.
+        Dictionary containing information about execution, with these keys:
+        • output: (string|nil) Output if `opts.output` is true.
 
     See also: ~
-        |execute()|
-        |nvim_command()|
-        |nvim_cmd()|
+      • |execute()|
+      • |nvim_command()|
+      • |nvim_cmd()|
 
                                                      *nvim_parse_expression()*
 nvim_parse_expression({expr}, {flags}, {highlight})
-    Parse a VimL expression.
+    Parse a Vimscript expression.
 
     Attributes: ~
         |api-fast|
@@ -1638,8 +1700,8 @@ nvim_parse_expression({expr}, {flags}, {highlight})
               stringified without "kExprNode" prefix.
             • "start": a pair [line, column] describing where node is
               "started" where "line" is always 0 (will not be 0 if you will be
-              using nvim_parse_viml() on e.g. ":let", but that is not present
-              yet). Both elements are Integers.
+              using this API on e.g. ":let", but that is not present yet).
+              Both elements are Integers.
             • "len": “length” of the node. This and "start" are there for
               debugging purposes primary (debugging parser and providing debug
               information).
@@ -1678,13 +1740,13 @@ Command Functions                                                *api-command*
 
                                               *nvim_buf_create_user_command()*
 nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts})
-    Create a new user command |user-commands| in the given buffer.
+    Creates a buffer-local command |user-commands|.
 
     Parameters: ~
       • {buffer}  Buffer handle, or 0 for current buffer.
 
     See also: ~
-        nvim_create_user_command
+      • nvim_create_user_command
 
                                                  *nvim_buf_del_user_command()*
 nvim_buf_del_user_command({buffer}, {name})
@@ -1722,7 +1784,7 @@ nvim_cmd({*cmd}, {*opts})                                         *nvim_cmd()*
     example, instead of `vim.cmd.bdelete{ count = 2 }`, you may do
     `vim.cmd.bdelete(2)`.
 
-    On execution error: fails with VimL error, updates v:errmsg.
+    On execution error: fails with Vimscript error, updates v:errmsg.
 
     Parameters: ~
       • {cmd}   Command to execute. Must be a Dictionary that can contain the
@@ -1738,22 +1800,19 @@ nvim_cmd({*cmd}, {*opts})                                         *nvim_cmd()*
         empty string.
 
     See also: ~
-        |nvim_exec()|
-        |nvim_command()|
+      • |nvim_exec2()|
+      • |nvim_command()|
 
                                                   *nvim_create_user_command()*
 nvim_create_user_command({name}, {command}, {*opts})
-    Create a new user command |user-commands|
+    Creates a global |user-commands| command.
 
-    {name} is the name of the new command. The name must begin with an
-    uppercase letter.
-
-    {command} is the replacement text or Lua function to execute.
+    For Lua usage see |lua-guide-commands-create|.
 
     Example: >vim
-       :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
-       :SayHello
-       Hello world!
+        :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
+        :SayHello
+        Hello world!
 <
 
     Parameters: ~
@@ -1769,6 +1828,7 @@ nvim_create_user_command({name}, {command}, {*opts})
                    • fargs: (table) The args split by unescaped whitespace
                      (when more than one argument is allowed), if any
                      |<f-args>|
+                   • nargs: (string) Number of arguments |:command-nargs|
                    • bang: (boolean) "true" if the command was executed with a
                      ! modifier |<bang>|
                    • line1: (number) The starting line of the command range
@@ -1783,19 +1843,20 @@ nvim_create_user_command({name}, {command}, {*opts})
                    • smods: (table) Command modifiers in a structured format.
                      Has the same structure as the "mods" key of
                      |nvim_parse_cmd()|.
-      • {opts}     Optional command attributes. See |command-attributes| for
-                   more details. To use boolean attributes (such as
-                   |:command-bang| or |:command-bar|) set the value to "true".
-                   In addition to the string options listed in
-                   |:command-complete|, the "complete" key also accepts a Lua
-                   function which works like the "customlist" completion mode
-                   |:command-completion-customlist|. Additional parameters:
-                   • desc: (string) Used for listing the command when a Lua
-                     function is used for {command}.
-                   • force: (boolean, default true) Override any previous
-                     definition.
-                   • preview: (function) Preview callback for 'inccommand'
-                     |:command-preview|
+      • {opts}     Optional |command-attributes|.
+                   • Set boolean attributes such as |:command-bang| or
+                     |:command-bar| to true (but not |:command-buffer|, use
+                     |nvim_buf_create_user_command()| instead).
+                   • "complete" |:command-complete| also accepts a Lua
+                     function which works like
+                     |:command-completion-customlist|.
+                   • Other parameters:
+                     • desc: (string) Used for listing the command when a Lua
+                       function is used for {command}.
+                     • force: (boolean, default true) Override any previous
+                       definition.
+                     • preview: (function) Preview callback for 'inccommand'
+                       |:command-preview|
 
 nvim_del_user_command({name})                        *nvim_del_user_command()*
     Delete a user-defined command.
@@ -1814,6 +1875,9 @@ nvim_get_commands({*opts})                               *nvim_get_commands()*
     Return: ~
         Map of maps describing commands.
 
+    See also: ~
+      • |nvim_get_all_options_info()|
+
 nvim_parse_cmd({str}, {opts})                               *nvim_parse_cmd()*
     Parse command line.
 
@@ -1889,45 +1953,20 @@ nvim_parse_cmd({str}, {opts})                               *nvim_parse_cmd()*
 ==============================================================================
 Options Functions                                                *api-options*
 
-nvim_buf_get_option({buffer}, {name})                  *nvim_buf_get_option()*
-    Gets a buffer option value
-
-    Parameters: ~
-      • {buffer}  Buffer handle, or 0 for current buffer
-      • {name}    Option name
-
-    Return: ~
-        Option value
-
-nvim_buf_set_option({buffer}, {name}, {value})         *nvim_buf_set_option()*
-    Sets a buffer option value. Passing `nil` as value deletes the option
-    (only works if there's a global fallback)
-
-    Parameters: ~
-      • {buffer}  Buffer handle, or 0 for current buffer
-      • {name}    Option name
-      • {value}   Option value
-
 nvim_get_all_options_info()                      *nvim_get_all_options_info()*
     Gets the option information for all options.
 
     The dictionary has the full option names as keys and option metadata
-    dictionaries as detailed at |nvim_get_option_info()|.
+    dictionaries as detailed at |nvim_get_option_info2()|.
 
     Return: ~
         dictionary of all options
 
-nvim_get_option({name})                                    *nvim_get_option()*
-    Gets the global value of an option.
-
-    Parameters: ~
-      • {name}  Option name
-
-    Return: ~
-        Option value (global)
+    See also: ~
+      • |nvim_get_commands()|
 
-nvim_get_option_info({name})                          *nvim_get_option_info()*
-    Gets the option information for one option
+nvim_get_option_info2({name}, {*opts})               *nvim_get_option_info2()*
+    Gets the option information for one option from arbitrary buffer or window
 
     Resulting dictionary has keys:
     • name: Name of the option (like 'filetype')
@@ -1943,8 +1982,19 @@ nvim_get_option_info({name})                          *nvim_get_option_info()*
     • commalist: List of comma separated values
     • flaglist: List of single char flags
 
+    When {scope} is not provided, the last set information applies to the
+    local value in the current buffer or window if it is available, otherwise
+    the global value information is returned. This behavior can be disabled by
+    explicitly specifying {scope} in the {opts} table.
+
     Parameters: ~
       • {name}  Option name
+      • {opts}  Optional parameters
+                • scope: One of "global" or "local". Analogous to |:setglobal|
+                  and |:setlocal|, respectively.
+                • win: |window-ID|. Used for getting window local options.
+                • buf: Buffer number. Used for getting buffer local options.
+                  Implies {scope} is "local".
 
     Return: ~
         Option Information
@@ -1963,17 +2013,14 @@ nvim_get_option_value({name}, {*opts})               *nvim_get_option_value()*
                 • win: |window-ID|. Used for getting window local options.
                 • buf: Buffer number. Used for getting buffer local options.
                   Implies {scope} is "local".
+                • filetype: |filetype|. Used to get the default option for a
+                  specific filetype. Cannot be used with any other option.
+                  Note: this will trigger |ftplugin| and all |FileType|
+                  autocommands for the corresponding filetype.
 
     Return: ~
         Option value
 
-nvim_set_option({name}, {value})                           *nvim_set_option()*
-    Sets the global value of an option.
-
-    Parameters: ~
-      • {name}   Option name
-      • {value}  New option value
-
                                                      *nvim_set_option_value()*
 nvim_set_option_value({name}, {value}, {*opts})
     Sets the value of an option. The behavior of this function matches that of
@@ -1991,25 +2038,6 @@ nvim_set_option_value({name}, {value}, {*opts})
                  • win: |window-ID|. Used for setting window local option.
                  • buf: Buffer number. Used for setting buffer local option.
 
-nvim_win_get_option({window}, {name})                  *nvim_win_get_option()*
-    Gets a window option value
-
-    Parameters: ~
-      • {window}  Window handle, or 0 for current window
-      • {name}    Option name
-
-    Return: ~
-        Option value
-
-nvim_win_set_option({window}, {name}, {value})         *nvim_win_set_option()*
-    Sets a window option value. Passing `nil` as value deletes the option
-    (only works if there's a global fallback)
-
-    Parameters: ~
-      • {window}  Window handle, or 0 for current window
-      • {name}    Option name
-      • {value}   Option value
-
 
 ==============================================================================
 Buffer Functions                                                  *api-buffer*
@@ -2017,7 +2045,7 @@ Buffer Functions                                                  *api-buffer*
 
 For more information on buffers, see |buffers|.
 
-Unloaded Buffers:~
+Unloaded Buffers: ~
 
 Buffers may be unloaded by the |:bunload| command or the buffer's
 |'bufhidden'| option. When a buffer is unloaded its file contents are
@@ -2032,10 +2060,14 @@ whether a buffer is loaded.
 nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
     Activates buffer-update events on a channel, or as Lua callbacks.
 
-    Example (Lua): capture buffer updates in a global `events` variable (use "print(vim.inspect(events))" to see its contents): >lua
-      events = {}
-      vim.api.nvim_buf_attach(0, false, {
-        on_lines=function(...) table.insert(events, {...}) end})
+    Example (Lua): capture buffer updates in a global `events` variable (use
+    "vim.print(events)" to see its contents): >lua
+        events = {}
+        vim.api.nvim_buf_attach(0, false, {
+          on_lines = function(...)
+            table.insert(events, {...})
+          end,
+        })
 <
 
     Parameters: ~
@@ -2057,7 +2089,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
                          • deleted_codepoints (if `utf_sizes` is true)
                          • deleted_codeunits (if `utf_sizes` is true)
 
-                       • on_bytes: lua callback invoked on change. This
+                       • on_bytes: Lua callback invoked on change. This
                          callback receives more granular information about the
                          change compared to on_lines. Return `true` to detach. Args:
                          • the string "bytes"
@@ -2099,8 +2131,8 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
         otherwise True. TODO: LUA_API_NO_EVAL
 
     See also: ~
-        |nvim_buf_detach()|
-        |api-buffer-updates-lua|
+      • |nvim_buf_detach()|
+      • |api-buffer-updates-lua|
 
 nvim_buf_call({buffer}, {fun})                               *nvim_buf_call()*
     call a function with buffer as temporary current buffer
@@ -2112,20 +2144,20 @@ nvim_buf_call({buffer}, {fun})                               *nvim_buf_call()*
     a temporary scratch window (called the "autocmd window" for historical
     reasons) will be used.
 
-    This is useful e.g. to call vimL functions that only work with the current
-    buffer/window currently, like |termopen()|.
+    This is useful e.g. to call Vimscript functions that only work with the
+    current buffer/window currently, like |termopen()|.
 
     Attributes: ~
         Lua |vim.api| only
 
     Parameters: ~
       • {buffer}  Buffer handle, or 0 for current buffer
-      • {fun}     Function to call inside the buffer (currently lua callable
+      • {fun}     Function to call inside the buffer (currently Lua callable
                   only)
 
     Return: ~
-        Return value of function. NB: will deepcopy lua values currently, use
-        upvalues to send lua references in and out.
+        Return value of function. NB: will deepcopy Lua values currently, use
+        upvalues to send Lua references in and out.
 
 nvim_buf_del_keymap({buffer}, {mode}, {lhs})           *nvim_buf_del_keymap()*
     Unmaps a buffer-local |mapping| for the given mode.
@@ -2134,13 +2166,13 @@ nvim_buf_del_keymap({buffer}, {mode}, {lhs})           *nvim_buf_del_keymap()*
       • {buffer}  Buffer handle, or 0 for current buffer
 
     See also: ~
-        |nvim_del_keymap()|
+      • |nvim_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: ~
@@ -2151,8 +2183,8 @@ nvim_buf_del_mark({buffer}, {name})                      *nvim_buf_del_mark()*
         true if the mark was deleted, else false.
 
     See also: ~
-        |nvim_buf_set_mark()|
-        |nvim_del_mark()|
+      • |nvim_buf_set_mark()|
+      • |nvim_del_mark()|
 
 nvim_buf_del_var({buffer}, {name})                        *nvim_buf_del_var()*
     Removes a buffer-scoped (b:) variable
@@ -2165,7 +2197,7 @@ nvim_buf_delete({buffer}, {opts})                          *nvim_buf_delete()*
     Deletes the buffer. See |:bwipeout|
 
     Attributes: ~
-        not allowed when |textlock| is active
+        not allowed when |textlock| is active or in the |cmdwin|
 
     Parameters: ~
       • {buffer}  Buffer handle, or 0 for current buffer
@@ -2187,8 +2219,8 @@ nvim_buf_detach({buffer})                                  *nvim_buf_detach()*
         True.
 
     See also: ~
-        |nvim_buf_attach()|
-        |api-lua-detach| for detaching Lua callbacks
+      • |nvim_buf_attach()|
+      • |api-lua-detach| for detaching Lua callbacks
 
 nvim_buf_get_changedtick({buffer})                *nvim_buf_get_changedtick()*
     Gets a changed tick of a buffer
@@ -2231,7 +2263,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|
@@ -2245,8 +2278,8 @@ nvim_buf_get_mark({buffer}, {name})                      *nvim_buf_get_mark()*
         uppercase/file mark set in another buffer.
 
     See also: ~
-        |nvim_buf_set_mark()|
-        |nvim_buf_del_mark()|
+      • |nvim_buf_set_mark()|
+      • |nvim_buf_del_mark()|
 
 nvim_buf_get_name({buffer})                              *nvim_buf_get_name()*
     Gets the full file name for the buffer
@@ -2322,8 +2355,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: ~
@@ -2349,7 +2382,7 @@ nvim_buf_set_keymap({buffer}, {mode}, {lhs}, {rhs}, {*opts})
       • {buffer}  Buffer handle, or 0 for current buffer
 
     See also: ~
-        |nvim_set_keymap()|
+      • |nvim_set_keymap()|
 
                                                         *nvim_buf_set_lines()*
 nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement})
@@ -2376,7 +2409,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement})
       • {replacement}      Array of lines to use as replacement
 
     See also: ~
-        |nvim_buf_set_text()|
+      • |nvim_buf_set_text()|
 
                                                          *nvim_buf_set_mark()*
 nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts})
@@ -2385,8 +2418,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
@@ -2399,8 +2432,8 @@ nvim_buf_set_mark({buffer}, {name}, {line}, {col}, {opts})
         true if the mark was set, else false.
 
     See also: ~
-        |nvim_buf_del_mark()|
-        |nvim_buf_get_mark()|
+      • |nvim_buf_del_mark()|
+      • |nvim_buf_get_mark()|
 
 nvim_buf_set_name({buffer}, {name})                      *nvim_buf_set_name()*
     Sets the full file name for a buffer
@@ -2428,6 +2461,11 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
     Prefer |nvim_buf_set_lines()| if you are only adding or deleting entire
     lines.
 
+    Prefer |nvim_put()| if you want to insert text at the cursor position.
+
+    Attributes: ~
+        not allowed when |textlock| is active
+
     Parameters: ~
       • {buffer}       Buffer handle, or 0 for current buffer
       • {start_row}    First line index
@@ -2437,7 +2475,8 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
       • {replacement}  Array of lines to use as replacement
 
     See also: ~
-        |nvim_buf_set_lines()|
+      • |nvim_buf_set_lines()|
+      • |nvim_put()|
 
 nvim_buf_set_var({buffer}, {name}, {value})               *nvim_buf_set_var()*
     Sets a buffer-scoped (b:) variable
@@ -2523,43 +2562,50 @@ nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts})
       • {id}      Extmark id
       • {opts}    Optional parameters. Keys:
                   • details: Whether to include the details dict
+                  • hl_name: Whether to include highlight group name instead
+                    of id, true if omitted
 
     Return: ~
         0-indexed (row, col) tuple or empty list () if extmark id was absent
 
                                                      *nvim_buf_get_extmarks()*
-nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
-    Gets |extmarks| in "traversal order" from a |charwise| region defined by
-    buffer positions (inclusive, 0-indexed |api-indexing|).
+nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts})
+    Gets |extmarks| (including |signs|) in "traversal order" from a |charwise|
+    region defined by buffer positions (inclusive, 0-indexed |api-indexing|).
 
     Region can be given as (row,col) tuples, or valid extmark ids (whose
     positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1)
     respectively, thus the following are equivalent: >lua
-      vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
-      vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {})
+        vim.api.nvim_buf_get_extmarks(0, my_ns, 0, -1, {})
+        vim.api.nvim_buf_get_extmarks(0, my_ns, {0,0}, {-1,-1}, {})
 <
 
     If `end` is less than `start`, traversal works backwards. (Useful with
     `limit`, to get the first marks prior to a given position.)
 
+    Note: when using extmark ranges (marks with a end_row/end_col position)
+    the `overlap` option might be useful. Otherwise only the start position of
+    an extmark will be considered.
+
     Example: >lua
-      local a   = vim.api
-      local pos = a.nvim_win_get_cursor(0)
-      local ns  = a.nvim_create_namespace('my-plugin')
-      -- Create new extmark at line 1, column 1.
-      local m1  = a.nvim_buf_set_extmark(0, ns, 0, 0, {})
-      -- Create new extmark at line 3, column 1.
-      local m2  = a.nvim_buf_set_extmark(0, ns, 2, 0, {})
-      -- Get extmarks only from line 3.
-      local ms  = a.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
-      -- Get all marks in this buffer + namespace.
-      local all = a.nvim_buf_get_extmarks(0, ns, 0, -1, {})
-      print(vim.inspect(ms))
+        local api = vim.api
+        local pos = api.nvim_win_get_cursor(0)
+        local ns  = api.nvim_create_namespace('my-plugin')
+        -- Create new extmark at line 1, column 1.
+        local m1  = api.nvim_buf_set_extmark(0, ns, 0, 0, {})
+        -- Create new extmark at line 3, column 1.
+        local m2  = api.nvim_buf_set_extmark(0, ns, 2, 0, {})
+        -- Get extmarks only from line 3.
+        local ms  = api.nvim_buf_get_extmarks(0, ns, {2,0}, {2,0}, {})
+        -- Get all marks in this buffer + namespace.
+        local all = api.nvim_buf_get_extmarks(0, ns, 0, -1, {})
+        vim.print(ms)
 <
 
     Parameters: ~
       • {buffer}  Buffer handle, or 0 for current buffer
-      • {ns_id}   Namespace id from |nvim_create_namespace()|
+      • {ns_id}   Namespace id from |nvim_create_namespace()| or -1 for all
+                  namespaces
       • {start}   Start of range: a 0-indexed (row, col) or valid extmark id
                   (whose position defines the bound). |api-indexing|
       • {end}     End of range (inclusive): a 0-indexed (row, col) or valid
@@ -2567,7 +2613,13 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
                   |api-indexing|
       • {opts}    Optional parameters. Keys:
                   • limit: Maximum number of marks to return
-                  • details Whether to include the details dict
+                  • details: Whether to include the details dict
+                  • hl_name: Whether to include highlight group name instead
+                    of id, true if omitted
+                  • overlap: Also include marks which overlap the range, even
+                    if their start position is less than `start`
+                  • type: Filter marks by type: "highlight", "sign",
+                    "virt_text" and "virt_lines"
 
     Return: ~
         List of [extmark_id, row, col] tuples in "traversal order".
@@ -2585,6 +2637,11 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts})
     Using the optional arguments, it is possible to use this to highlight a
     range of text, and also to associate virtual text to the mark.
 
+    If present, the position defined by `end_col` and `end_row` should be
+    after the start position in order for the extmark to cover a range. An
+    earlier end position is not an error, but then it behaves like an empty
+    range (no highlighting).
+
     Parameters: ~
       • {buffer}  Buffer handle, or 0 for current buffer
       • {ns_id}   Namespace id from |nvim_create_namespace()|
@@ -2608,23 +2665,28 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts})
                     string or as an integer, the latter which can be obtained
                     using |nvim_get_hl_id_by_name()|.
                   • virt_text_pos : position of virtual text. Possible values:
-                    • "eol": right after eol character (default)
+                    • "eol": right after eol character (default).
                     • "overlay": display over the specified column, without
                       shifting the underlying text.
                     • "right_align": display right aligned in the window.
+                    • "inline": display at the specified column, and shift the
+                      buffer text to the right as needed.
 
                   • virt_text_win_col : position the virtual text at a fixed
-                    window column (starting from the first text column)
+                    window column (starting from the first text column of the
+                    screen line) instead of "virt_text_pos".
                   • virt_text_hide : hide the virtual text when the background
-                    text is selected or hidden due to horizontal scroll
-                    'nowrap'
+                    text is selected or hidden because of scrolling with
+                    'nowrap' or 'smoothscroll'. Currently only affects
+                    "overlay" virt_text.
                   • hl_mode : control how highlights are combined with the
                     highlights of the text. Currently only affects virt_text
                     highlights, but might affect `hl_group` in later versions.
                     • "replace": only show the virt_text color. This is the
-                      default
-                    • "combine": combine with background text color
-                    • "blend": blend with background text color.
+                      default.
+                    • "combine": combine with background text color.
+                    • "blend": blend with background text color. Not supported
+                      for "inline" virt_text.
 
                   • virt_lines : virtual lines to add next to this mark This
                     should be an array over lines, where each line in turn is
@@ -2644,11 +2706,17 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts})
                     buffer.
                   • right_gravity : boolean that indicates the direction the
                     extmark will be shifted in when new text is inserted (true
-                    for right, false for left). defaults to true.
+                    for right, false for left). Defaults to true.
                   • end_right_gravity : boolean that indicates the direction
                     the extmark end position (if it exists) will be shifted in
                     when new text is inserted (true for right, false for
                     left). Defaults to false.
+                  • undo_restore : Restore the exact position of the mark if
+                    text around the mark was deleted and then restored by
+                    undo. Defaults to true.
+                  • invalidate : boolean that indicates whether to hide the
+                    extmark if the entirety of its range is deleted. If
+                    "undo_restore" is false, the extmark is deleted instead.
                   • priority: a priority value for the highlight group or sign
                     attribute. For example treesitter highlighting uses a
                     value of 100.
@@ -2712,14 +2780,14 @@ nvim_get_namespaces()                                  *nvim_get_namespaces()*
 nvim_set_decoration_provider({ns_id}, {*opts})
     Set or change decoration provider for a |namespace|
 
-    This is a very general purpose interface for having lua callbacks being
+    This is a very general purpose interface for having Lua callbacks being
     triggered during the redraw code.
 
     The expected usage is to set |extmarks| for the currently redrawn buffer.
     |nvim_buf_set_extmark()| can be called to add marks on a per-window or
     per-lines basis. Use the `ephemeral` key to only use the mark for the
     current screen redraw (the callback will be called again for the next
-    redraw ).
+    redraw).
 
     Note: this function should not be called often. Rather, the callbacks
     themselves can be used to throttle unneeded callbacks. the `on_start`
@@ -2731,11 +2799,14 @@ nvim_set_decoration_provider({ns_id}, {*opts})
     for the extmarks set/modified inside the callback anyway.
 
     Note: doing anything other than setting extmarks is considered
-    experimental. Doing things like changing options are not expliticly
+    experimental. Doing things like changing options are not explicitly
     forbidden, but is likely to have unexpected consequences (such as 100% CPU
     consumption). doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is
     quite dubious for the moment.
 
+    Note: It is not allowed to remove or update extmarks in 'on_line'
+    callbacks.
+
     Attributes: ~
         Lua |vim.api| only
 
@@ -2747,7 +2818,9 @@ nvim_set_decoration_provider({ns_id}, {*opts})
                  • on_buf: called for each buffer being redrawn (before window
                    callbacks) ["buf", bufnr, tick]
                  • on_win: called when starting to redraw a specific window.
-                   ["win", winid, bufnr, topline, botline_guess]
+                   botline_guess is an approximation that does not exceed the
+                   last line number. ["win", winid, bufnr, topline,
+                   botline_guess]
                  • on_line: called for each buffer line being redrawn. (The
                    interaction with fold lines is subject to change) ["win",
                    winid, bufnr, row]
@@ -2765,16 +2838,16 @@ nvim_win_call({window}, {fun})                               *nvim_win_call()*
 
     Parameters: ~
       • {window}  Window handle, or 0 for current window
-      • {fun}     Function to call inside the window (currently lua callable
+      • {fun}     Function to call inside the window (currently Lua callable
                   only)
 
     Return: ~
-        Return value of function. NB: will deepcopy lua values currently, use
-        upvalues to send lua references in and out.
+        Return value of function. NB: will deepcopy Lua values currently, use
+        upvalues to send Lua references in and out.
 
     See also: ~
-        |win_execute()|
-        |nvim_buf_call()|
+      • |win_execute()|
+      • |nvim_buf_call()|
 
 nvim_win_close({window}, {force})                           *nvim_win_close()*
     Closes the window (like |:close| with a |window-ID|).
@@ -2815,6 +2888,9 @@ nvim_win_get_cursor({window})                          *nvim_win_get_cursor()*
     Return: ~
         (row, col) tuple
 
+    See also: ~
+      • |getcurpos()|
+
 nvim_win_get_height({window})                          *nvim_win_get_height()*
     Gets the window height
 
@@ -2919,8 +2995,9 @@ nvim_win_set_height({window}, {height})                *nvim_win_set_height()*
       • {height}  Height as a count of rows
 
 nvim_win_set_hl_ns({window}, {ns_id})                   *nvim_win_set_hl_ns()*
-    Set highlight namespace for a window. This will use highlights defined in
-    this namespace, but fall back to global highlights (ns=0) when missing.
+    Set highlight namespace for a window. This will use highlights defined
+    with |nvim_set_hl()| for this namespace, but fall back to global
+    highlights (ns=0) when missing.
 
     This takes precedence over the 'winhighlight' option.
 
@@ -2943,6 +3020,40 @@ nvim_win_set_width({window}, {width})                   *nvim_win_set_width()*
       • {window}  Window handle, or 0 for current window
       • {width}   Width as a count of columns
 
+nvim_win_text_height({window}, {*opts})               *nvim_win_text_height()*
+    Computes the number of screen lines occupied by a range of text in a given
+    window. Works for off-screen text and takes folds into account.
+
+    Diff filler or virtual lines above a line are counted as a part of that
+    line, unless the line is on "start_row" and "start_vcol" is specified.
+
+    Diff filler or virtual lines below the last buffer line are counted in the
+    result when "end_row" is omitted.
+
+    Line indexing is similar to |nvim_buf_get_text()|.
+
+    Parameters: ~
+      • {window}  Window handle, or 0 for current window.
+      • {opts}    Optional parameters:
+                  • start_row: Starting line index, 0-based inclusive. When
+                    omitted start at the very top.
+                  • end_row: Ending line index, 0-based inclusive. When
+                    omitted end at the very bottom.
+                  • start_vcol: Starting virtual column index on "start_row",
+                    0-based inclusive, rounded down to full screen lines. When
+                    omitted include the whole line.
+                  • end_vcol: Ending virtual column index on "end_row",
+                    0-based exclusive, rounded up to full screen lines. When
+                    omitted include the whole line.
+
+    Return: ~
+        Dictionary containing text height information, with these keys:
+        • all: The total number of screen lines occupied by the range.
+        • fill: The number of diff filler or virtual lines among them.
+
+    See also: ~
+      • |virtcol()| for text width.
+
 
 ==============================================================================
 Win_Config Functions                                          *api-win_config*
@@ -2980,6 +3091,7 @@ nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
     Example (Lua): buffer-relative float (travels as buffer is scrolled) >lua
         vim.api.nvim_open_win(0, false,
           {relative='win', width=12, height=3, bufpos={100,10}})
+        })
 <
 
     Attributes: ~
@@ -3035,8 +3147,8 @@ nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
                       In general, values below 100 are recommended, unless
                       there is a good reason to overshadow builtin elements.
 
-                  • style: Configure the appearance of the window. Currently
-                    only takes one non-empty value:
+                  • style: (optional) Configure the appearance of the window.
+                    Currently only supports one value:
                     • "minimal" Nvim will display the window with many UI
                       options disabled. This is useful when displaying a
                       temporary float where the text should not be edited.
@@ -3059,7 +3171,7 @@ nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
                     • "shadow": A drop shadow effect by blending with the
                       background.
                     • If it is an array, it should have a length of eight or
-                      any divisor of eight. The array will specifify the eight
+                      any divisor of eight. The array will specify the eight
                       chars building up the border in a clockwise fashion
                       starting with the top-left corner. As an example, the
                       double box style could be specified as [ "╔", "═" ,"╗",
@@ -3075,14 +3187,24 @@ nvim_open_win({buffer}, {enter}, {*config})                  *nvim_open_win()*
                       specified by character: [ ["+", "MyCorner"], ["x",
                       "MyBorder"] ].
 
-                  • title: Title (optional) in window border, String or list.
-                    List is [text, highlight] tuples. if is string the default
-                    highlight group is `FloatTitle`.
-                  • title_pos: Title position must set with title option.
-                    value can be of `left` `center` `right` default is left.
+                  • title: Title (optional) in window border, string or list.
+                    List should consist of `[text, highlight]` tuples. If
+                    string, the default highlight group is `FloatTitle`.
+                  • title_pos: Title position. Must be set with `title`
+                    option. Value can be one of "left", "center", or "right".
+                    Default is `"left"`.
+                  • footer: Footer (optional) in window border, string or
+                    list. List should consist of `[text, highlight]` tuples.
+                    If string, the default highlight group is `FloatFooter`.
+                  • footer_pos: Footer position. Must be set with `footer`
+                    option. Value can be one of "left", "center", or "right".
+                    Default is `"left"`.
                   • noautocmd: If true then no buffer-related autocommand
                     events such as |BufEnter|, |BufLeave| or |BufWinEnter| may
                     fire from calling this function.
+                  • fixed: If true when anchor is NW or SW, the float window
+                    would be kept fixed even if the window would be truncated.
+                  • hide: If true the floating window will be hidden.
 
     Return: ~
         Window handle, or 0 on error
@@ -3112,7 +3234,7 @@ nvim_win_set_config({window}, {*config})               *nvim_win_set_config()*
       • {config}  Map defining the window configuration, see |nvim_open_win()|
 
     See also: ~
-        |nvim_open_win()|
+      • |nvim_open_win()|
 
 
 ==============================================================================
@@ -3185,8 +3307,8 @@ nvim_tabpage_set_var({tabpage}, {name}, {value})
 Autocmd Functions                                                *api-autocmd*
 
 nvim_clear_autocmds({*opts})                           *nvim_clear_autocmds()*
-    Clear all autocommands that match the corresponding {opts}. To delete a
-    particular autocmd, see |nvim_del_autocmd()|.
+    Clears all autocommands selected by {opts}. To delete autocmds see
+    |nvim_del_autocmd()|.
 
     Parameters: ~
       • {opts}  Parameters
@@ -3230,7 +3352,7 @@ nvim_create_augroup({name}, {*opts})                   *nvim_create_augroup()*
         Integer id of the created group.
 
     See also: ~
-        |autocmd-groups|
+      • |autocmd-groups|
 
 nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
     Creates an |autocommand| event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string).
@@ -3239,7 +3361,7 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
         vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
           pattern = {"*.c", "*.h"},
           callback = function(ev)
-            print(string.format('event fired: s', vim.inspect(ev)))
+            print(string.format('event fired: %s', vim.inspect(ev)))
           end
         })
 <
@@ -3251,9 +3373,9 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
         })
 <
 
-    Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), thus names like
-    "$HOME" and "~" must be expanded explicitly: >lua
-      pattern = vim.fn.expand("~") .. "/some/path/*.py"
+    Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|),
+    thus names like "$HOME" and "~" must be expanded explicitly: >lua
+        pattern = vim.fn.expand("~") .. "/some/path/*.py"
 <
 
     Parameters: ~
@@ -3281,7 +3403,7 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
                    • match: (string) expanded value of |<amatch>|
                    • buf: (number) expanded value of |<abuf>|
                    • file: (string) expanded value of |<afile>|
-                   • data: (any) arbitrary data passed to
+                   • data: (any) arbitrary data passed from
                      |nvim_exec_autocmds()|
 
                  • command (string) optional: Vim command to execute on event.
@@ -3295,8 +3417,8 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
         Autocommand id (number)
 
     See also: ~
-        |autocommand|
-        |nvim_del_autocmd()|
+      • |autocommand|
+      • |nvim_del_autocmd()|
 
 nvim_del_augroup_by_id({id})                        *nvim_del_augroup_by_id()*
     Delete an autocommand group by id.
@@ -3311,8 +3433,8 @@ nvim_del_augroup_by_id({id})                        *nvim_del_augroup_by_id()*
       • {id}  Integer The id of the group.
 
     See also: ~
-        |nvim_del_augroup_by_name()|
-        |nvim_create_augroup()|
+      • |nvim_del_augroup_by_name()|
+      • |nvim_create_augroup()|
 
 nvim_del_augroup_by_name({name})                  *nvim_del_augroup_by_name()*
     Delete an autocommand group by name.
@@ -3325,18 +3447,13 @@ nvim_del_augroup_by_name({name})                  *nvim_del_augroup_by_name()*
       • {name}  String The name of the group.
 
     See also: ~
-        |autocmd-groups|
+      • |autocmd-groups|
 
 nvim_del_autocmd({id})                                    *nvim_del_autocmd()*
-    Delete an autocommand by id.
-
-    NOTE: Only autocommands created via the API have an id.
+    Deletes an autocommand by id.
 
     Parameters: ~
-      • {id}  Integer The id returned by nvim_create_autocmd
-
-    See also: ~
-        |nvim_create_autocmd()|
+      • {id}  Integer Autocommand id returned by |nvim_create_autocmd()|
 
 nvim_exec_autocmds({event}, {*opts})                    *nvim_exec_autocmds()*
     Execute all autocommands for {event} that match the corresponding {opts}
@@ -3357,23 +3474,23 @@ nvim_exec_autocmds({event}, {*opts})                    *nvim_exec_autocmds()*
                    callback. See |nvim_create_autocmd()| for details.
 
     See also: ~
-        |:doautocmd|
+      • |:doautocmd|
 
 nvim_get_autocmds({*opts})                               *nvim_get_autocmds()*
     Get all autocommands that match the corresponding {opts}.
 
     These examples will get autocommands matching ALL the given criteria: >lua
-      -- Matches all criteria
-      autocommands = vim.api.nvim_get_autocmds({
-        group = "MyGroup",
-        event = {"BufEnter", "BufWinEnter"},
-        pattern = {"*.c", "*.h"}
-      })
-
-      -- All commands from one group
-      autocommands = vim.api.nvim_get_autocmds({
-        group = "MyGroup",
-      })
+        -- Matches all criteria
+        autocommands = vim.api.nvim_get_autocmds({
+          group = "MyGroup",
+          event = {"BufEnter", "BufWinEnter"},
+          pattern = {"*.c", "*.h"}
+        })
+
+        -- All commands from one group
+        autocommands = vim.api.nvim_get_autocmds({
+          group = "MyGroup",
+        })
 <
 
     NOTE: When multiple patterns or events are provided, it will find all the
@@ -3420,8 +3537,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.
 
@@ -3484,6 +3601,22 @@ nvim_ui_set_option({name}, {value})                     *nvim_ui_set_option()*
     Attributes: ~
         |RPC| only
 
+nvim_ui_term_event({event}, {value})                    *nvim_ui_term_event()*
+    Tells Nvim when a terminal event has occurred
+
+    The following terminal events are supported:
+
+    • "termresponse": The terminal sent an OSC or DCS response sequence to
+      Nvim. The payload is the received response. Sets |v:termresponse| and
+      fires |TermResponse|.
+
+    Attributes: ~
+        |RPC| only
+
+    Parameters: ~
+      • {event}    Event name
+      • {payload}  Event payload
+
 nvim_ui_try_resize({width}, {height})                   *nvim_ui_try_resize()*
     TODO: Documentation