doc: |api-fast| [ci skip]

1 files changed, 69 insertions, 49 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 3b641760f7..bb4274a661 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -133,6 +133,14 @@ lines, 0-based columns):
     |nvim_win_get_cursor()|
     |nvim_win_set_cursor()|
 
+							*api-fast*
+Most API functions are "deferred": they are queued on the main loop and
+processed sequentially with normal input.  So if the editor is waiting for
+user input in a "modal" fashion (e.g. the |hit-enter-prompt|), the request
+will block.  Non-deferred ({fast}) functions such as |nvim_get_mode()| and
+|nvim_input()| are served immediately (i.e. without waiting in the input
+queue).  Lua code can use |vim.in_fast_event()| to detect a {fast} context.
+
 ==============================================================================
 API metadata						*api-metadata*
 
@@ -506,7 +514,7 @@ nvim_input({keys})                                              *nvim_input()*
                     |api-level| 6.
 
                 Attributes: ~
-                    {async}
+                    {fast}
 
                 Parameters: ~
                     {keys}  to be typed
@@ -531,7 +539,7 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
                     |nvim_input()| has the same limitiation.
 
                 Attributes: ~
-                    {async}
+                    {fast}
 
                 Parameters: ~
                     {button}    Mouse button: one of "left", "right",
@@ -808,7 +816,7 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
 
                 Currently this is used to open floating and external windows.
                 Floats are windows that are drawn above the split layout, at
-                some anchor position in some other window. Floats can be draw
+                some anchor position in some other window. Floats can be drawn
                 internally or by external GUI with the |ui-multigrid|
                 extension. External windows are only supported with multigrid
                 GUIs, and are displayed as separate top-level windows.
@@ -860,6 +868,14 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                                 Minimum of 1.
                               • `width` : window width (in character cells).
                                 Minimum of 1.
+                              • 'bufpos': position float relative text inside
+                                window `win` (only when relative="win"). Takes
+                                a tuple of zero-indexed [line, column]. Note:
+                                `row` and `col` if present, still applies
+                                relative this position. By default `row=1` and
+                                `col=0` are used (with default NW anchor), to
+                                make the float behave like a tooltip under the
+                                buffer text.
                               • `row` : row position. Screen cell height are
                                 used as unit. Can be floating point.
                               • `col` : column position. Screen cell width is
@@ -880,12 +896,12 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                                   when displaing a temporary float where the
                                   text should not be edited. Disables
                                   'number', 'relativenumber', 'cursorline',
-                                  'cursorcolumn', 'spell' and 'list' options.
-                                  'signcolumn' is changed to `auto` . The
-                                  end-of-buffer region is hidden by setting
-                                  `eob` flag of 'fillchars' to a space char,
-                                  and clearing the |EndOfBuffer| region in
-                                  'winhighlight'.
+                                  'cursorcolumn', 'foldcolumn', 'spell' and
+                                  'list' options. 'signcolumn' is changed to
+                                  `auto` . The end-of-buffer region is hidden
+                                  by setting `eob` flag of 'fillchars' to a
+                                  space char, and clearing the |EndOfBuffer|
+                                  region in 'winhighlight'.
                               • top-level window. Currently accepts no other
                                 positioning configuration together with this.
 
@@ -1040,7 +1056,7 @@ nvim_get_mode()                                              *nvim_get_mode()*
                     Dictionary { "mode": String, "blocking": Boolean }
 
                 Attributes: ~
-                    {async}
+                    {fast}
 
 nvim_get_keymap({mode})                                    *nvim_get_keymap()*
                 Gets a list of global (non-buffer-local) |mapping|
@@ -1110,7 +1126,7 @@ nvim_get_api_info()                                      *nvim_get_api_info()*
                     2-tuple [{channel-id}, {api-metadata}]
 
                 Attributes: ~
-                    {async}
+                    {fast}
 
                                                       *nvim_set_client_info()*
 nvim_set_client_info({name}, {version}, {type}, {methods},
@@ -1243,7 +1259,7 @@ nvim_parse_expression({expr}, {flags}, {highlight})
                 Parse a VimL expression.
 
                 Attributes: ~
-                    {async}
+                    {fast}
 
                 Parameters: ~
                     {expr}       Expression to parse. Always treated as a
@@ -1475,12 +1491,16 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
                                    first notification will be a
                                    `nvim_buf_changedtick_event` . Not used for
                                    lua callbacks.
-                    {opts}         Optional parameters. `on_lines` : lua
-                                   callback received on change.
-                                   `on_changedtick` : lua callback received on
-                                   changedtick increment without text change.
-                                   See |api-buffer-updates-lua| for more
-                                   information
+                    {opts}         Optional parameters.
+                                   • `on_lines` : lua callback received on
+                                     change.
+                                   • `on_changedtick` : lua callback received
+                                     on changedtick increment without text
+                                     change.
+                                   • `utf_sizes` : include UTF-32 and UTF-16
+                                     size of the replaced region. See
+                                     |api-buffer-updates-lua| for more
+                                     information
 
                 Return: ~
                     False when updates couldn't be enabled because the buffer
@@ -1802,6 +1822,9 @@ nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts})
                 Return: ~
                     The ns_id that was used
 
+nvim__buf_stats({buffer})                                  *nvim__buf_stats()*
+                TODO: Documentation
+
 
 ==============================================================================
 Window Functions                                                  *api-window*
@@ -1810,7 +1833,7 @@ nvim_win_get_buf({window})                                *nvim_win_get_buf()*
                 Gets the current buffer in a window
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
 
                 Return: ~
                     Buffer handle
@@ -1819,7 +1842,7 @@ nvim_win_set_buf({window}, {buffer})                      *nvim_win_set_buf()*
                 Sets the current buffer in a window, without side-effects
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
                     {buffer}  Buffer handle
 
 nvim_win_get_cursor({window})                          *nvim_win_get_cursor()*
@@ -1827,7 +1850,7 @@ nvim_win_get_cursor({window})                          *nvim_win_get_cursor()*
                 |api-indexing|
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
 
                 Return: ~
                     (row, col) tuple
@@ -1837,14 +1860,14 @@ nvim_win_set_cursor({window}, {pos})                   *nvim_win_set_cursor()*
                 |api-indexing|
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
                     {pos}     (row, col) tuple representing the new position
 
 nvim_win_get_height({window})                          *nvim_win_get_height()*
                 Gets the window height
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
 
                 Return: ~
                     Height as a count of rows
@@ -1854,14 +1877,14 @@ nvim_win_set_height({window}, {height})                *nvim_win_set_height()*
                 is split horizontally.
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
                     {height}  Height as a count of rows
 
 nvim_win_get_width({window})                            *nvim_win_get_width()*
                 Gets the window width
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
 
                 Return: ~
                     Width as a count of columns
@@ -1871,14 +1894,14 @@ nvim_win_set_width({window}, {width})                   *nvim_win_set_width()*
                 split vertically.
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
                     {width}   Width as a count of columns
 
 nvim_win_get_var({window}, {name})                        *nvim_win_get_var()*
                 Gets a window-scoped (w:) variable
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
                     {name}    Variable name
 
                 Return: ~
@@ -1888,7 +1911,7 @@ nvim_win_set_var({window}, {name}, {value})               *nvim_win_set_var()*
                 Sets a window-scoped (w:) variable
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
                     {name}    Variable name
                     {value}   Variable value
 
@@ -1896,14 +1919,14 @@ nvim_win_del_var({window}, {name})                        *nvim_win_del_var()*
                 Removes a window-scoped (w:) variable
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
                     {name}    Variable name
 
 nvim_win_get_option({window}, {name})                  *nvim_win_get_option()*
                 Gets a window option value
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
                     {name}    Option name
 
                 Return: ~
@@ -1914,7 +1937,7 @@ nvim_win_set_option({window}, {name}, {value})         *nvim_win_set_option()*
                 option(only works if there's a global fallback)
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
                     {name}    Option name
                     {value}   Option value
 
@@ -1923,7 +1946,7 @@ nvim_win_get_position({window})                      *nvim_win_get_position()*
                 zero.
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
 
                 Return: ~
                     (row, col) tuple with the window position
@@ -1932,7 +1955,7 @@ nvim_win_get_tabpage({window})                        *nvim_win_get_tabpage()*
                 Gets the window tabpage
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
 
                 Return: ~
                     Tabpage that contains the window
@@ -1941,7 +1964,7 @@ nvim_win_get_number({window})                          *nvim_win_get_number()*
                 Gets the window number
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
 
                 Return: ~
                     Window number
@@ -1950,7 +1973,7 @@ nvim_win_is_valid({window})                              *nvim_win_is_valid()*
                 Checks if a window is valid
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
 
                 Return: ~
                     true if the window is valid, false otherwise
@@ -1969,7 +1992,7 @@ nvim_win_set_config({window}, {config})                *nvim_win_set_config()*
                 subset of these is an error.
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
                     {config}  Dictionary of window configuration
 
 nvim_win_get_config({window})                          *nvim_win_get_config()*
@@ -1981,19 +2004,16 @@ nvim_win_get_config({window})                          *nvim_win_get_config()*
                 `relative` will be an empty string for normal windows.
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
 
                 Return: ~
                     Window configuration
 
 nvim_win_close({window}, {force})                           *nvim_win_close()*
-                Close a window.
-
-                This is equivalent to |:close| with count except that it takes
-                a window id.
+                Closes the window (like |:close| with a |window-ID|).
 
                 Parameters: ~
-                    {window}  Window handle
+                    {window}  Window handle, or 0 for current window
                     {force}   Behave like `:close!` The last window of a
                               buffer with unwritten changes can be closed. The
                               buffer will become hidden, even if 'hidden' is
@@ -2007,7 +2027,7 @@ nvim_tabpage_list_wins({tabpage})                   *nvim_tabpage_list_wins()*
                 Gets the windows in a tabpage
 
                 Parameters: ~
-                    {tabpage}  Tabpage
+                    {tabpage}  Tabpage handle, or 0 for current tabpage
 
                 Return: ~
                     List of windows in `tabpage`
@@ -2016,7 +2036,7 @@ nvim_tabpage_get_var({tabpage}, {name})               *nvim_tabpage_get_var()*
                 Gets a tab-scoped (t:) variable
 
                 Parameters: ~
-                    {tabpage}  Tabpage handle
+                    {tabpage}  Tabpage handle, or 0 for current tabpage
                     {name}     Variable name
 
                 Return: ~
@@ -2026,7 +2046,7 @@ nvim_tabpage_set_var({tabpage}, {name}, {value})      *nvim_tabpage_set_var()*
                 Sets a tab-scoped (t:) variable
 
                 Parameters: ~
-                    {tabpage}  Tabpage handle
+                    {tabpage}  Tabpage handle, or 0 for current tabpage
                     {name}     Variable name
                     {value}    Variable value
 
@@ -2034,14 +2054,14 @@ nvim_tabpage_del_var({tabpage}, {name})               *nvim_tabpage_del_var()*
                 Removes a tab-scoped (t:) variable
 
                 Parameters: ~
-                    {tabpage}  Tabpage handle
+                    {tabpage}  Tabpage handle, or 0 for current tabpage
                     {name}     Variable name
 
 nvim_tabpage_get_win({tabpage})                       *nvim_tabpage_get_win()*
                 Gets the current window in a tabpage
 
                 Parameters: ~
-                    {tabpage}  Tabpage handle
+                    {tabpage}  Tabpage handle, or 0 for current tabpage
 
                 Return: ~
                     Window handle
@@ -2050,7 +2070,7 @@ nvim_tabpage_get_number({tabpage})                 *nvim_tabpage_get_number()*
                 Gets the tabpage number
 
                 Parameters: ~
-                    {tabpage}  Tabpage handle
+                    {tabpage}  Tabpage handle, or 0 for current tabpage
 
                 Return: ~
                     Tabpage number
@@ -2059,7 +2079,7 @@ nvim_tabpage_is_valid({tabpage})                     *nvim_tabpage_is_valid()*
                 Checks if a tabpage is valid
 
                 Parameters: ~
-                    {tabpage}  Tabpage handle
+                    {tabpage}  Tabpage handle, or 0 for current tabpage
 
                 Return: ~
                     true if the tabpage is valid, false otherwise