doc: |api-fast| [ci skip]

3 files changed, 102 insertions, 70 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
diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt
index 68e94ef5c5..284cd26583 100644
--- a/runtime/doc/help.txt
+++ b/runtime/doc/help.txt
@@ -137,7 +137,6 @@ Special issues ~
 Programming language support ~
 |indent.txt|	automatic indenting for C and other languages
 |syntax.txt|	syntax highlighting
-|textprop.txt|	Attaching properties to text for highlighting or other
 |filetype.txt|	settings done specifically for a type of file
 |quickfix.txt|	commands for a quick edit-compile-fix cycle
 |ft_ada.txt|	Ada (the programming language) support
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
index 1837e14623..11950da91e 100644
--- a/runtime/doc/if_lua.txt
+++ b/runtime/doc/if_lua.txt
@@ -373,37 +373,31 @@ Example: to use the "nvim_get_current_line()" API function, call
 ------------------------------------------------------------------------------
 VIM.LOOP						*lua-loop*
 
-`vim.loop` exposes all features of the Nvim event-loop.  This is a lower-level
+`vim.loop` exposes all features of the Nvim event-loop.  This is a low-level
 API that provides functionality for networking, filesystem, and process
 management.  Try this command to see available functions: >
 
     :lua print(vim.inspect(vim.loop))
 
-See http://docs.libuv.org for complete documentation.
-See https://github.com/luvit/luv/tree/master/examples for examples.
+Reference: http://docs.libuv.org
+Examples:  https://github.com/luvit/luv/tree/master/examples
 
 						*E5560* *lua-loop-callbacks*
-Note: it is not allowed to directly invoke most of the Nvim API from `vim.loop`
-callbacks.  This will result in an error: >
+It is an error to directly invoke `vim.api` functions (except |api-fast|) in
+`vim.loop` callbacks.  For example, this is an error: >
 
     local timer = vim.loop.new_timer()
     timer:start(1000, 0, function()
       vim.api.nvim_command('echomsg "test"')
     end)
 
-The `vim.schedule_wrap` helper can be used to defer the callback until it
-is safe to execute API methods. >
+To avoid the error use |vim.schedule_wrap()| to defer the callback: >
 
     local timer = vim.loop.new_timer()
     timer:start(1000, 0, vim.schedule_wrap(function()
       vim.api.nvim_command('echomsg "test"')
     end))
 
-A subset of the API is available in direct luv callbacks ("fast" callbacks),
-most notably |nvim_get_mode()| and |nvim_input()|.  It is possible to
-check whether code is running in this context using |vim.in_fast_event()|.
-
-
 Example: repeating timer
     1. Save this code to a file.
     2. Execute it with ":luafile %". >
@@ -454,6 +448,13 @@ Example: TCP echo-server				*tcp-server*
 ------------------------------------------------------------------------------
 VIM							*lua-util*
 
+vim.in_fast_event()					*vim.in_fast_event()*
+        Returns true if the code is executing as part of a "fast" event
+        handler, where most of the API is disabled. These are low-level events
+        (e.g. |lua-loop-callbacks|) which can be invoked whenever Nvim polls
+        for input.  When this is `false` most API functions are callable (but
+        may be subject to other restrictions such as |textlock|).
+
 vim.stricmp({a}, {b})					*vim.stricmp()*
         Compares strings case-insensitively.  Returns 0, 1 or -1 if strings
         are equal, {a} is greater than {b} or {a} is lesser than {b},
@@ -481,14 +482,6 @@ vim.schedule({callback})				*vim.schedule()*
         Schedules {callback} to be invoked soon by the main event-loop. Useful
         to avoid |textlock| or other temporary restrictions.
 
-vim.in_fast_event()					*vim.in_fast_event()*
-        Returns true if the code is executing as part of a "fast" event
-        handler, where most of the API is disabled. These are low-level event
-        such as luv callbacks |lua-loop-callbacks|, which can be invoked at
-        any time nvim polls for input. When this returns `false` most API
-        functions are callable, but can be subjected to other restrictions,
-        such as |textlock|.
-
 vim.type_idx						*vim.type_idx*
 	Type index for use in |lua-special-tbl|.  Specifying one of the 
 	values from |vim.types| allows typing the empty table (it is 
@@ -552,6 +545,14 @@ paste({lines}, {phase})                                          *vim.paste()*
                 See also: ~
                     |paste|
 
+schedule_wrap({cb})                                      *vim.schedule_wrap()*
+                Defers callback `cb` until the Nvim API is safe to call.
+
+                See also: ~
+                    |lua-loop-callbacks|
+                    |vim.schedule()|
+                    |vim.in_fast_event()|
+
 
 
 
@@ -651,4 +652,16 @@ trim({s})                                                         *vim.trim()*
                 See also: ~
                     https://www.lua.org/pil/20.2.html
 
+pesc({s})                                                         *vim.pesc()*
+                Escapes magic chars in a Lua pattern string.
+
+                Parameters: ~
+                    {s}  String to escape
+
+                Return: ~
+                    %-escaped pattern string
+
+                See also: ~
+                    https://github.com/rxi/lume
+
  vim:tw=78:ts=8:ft=help:norl: