doc: |api-fast| [ci skip]

9 files changed, 147 insertions, 113 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:
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index edfb38e617..373a58d11e 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -113,7 +113,7 @@ param_exclude = (
 
 # Annotations are displayed as line items after API function descriptions.
 annotation_map = {
-    'FUNC_API_ASYNC': '{async}',
+    'FUNC_API_FAST': '{fast}',
 }
 
 
@@ -485,7 +485,7 @@ def parse_source_xml(filename, mode):
         # XXX: (doxygen 1.8.11) 'argsstring' only includes attributes of
         # non-void functions.  Special-case void functions here.
         if name == 'nvim_get_mode' and len(annotations) == 0:
-            annotations += 'FUNC_API_ASYNC'
+            annotations += 'FUNC_API_FAST'
         annotations = filter(None, map(lambda x: annotation_map.get(x),
                                        annotations.split()))
 
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 690497159a..19ca25837a 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -110,10 +110,10 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
 ///        `nvim_buf_lines_event`. Otherwise, the first notification will be
 ///        a `nvim_buf_changedtick_event`. Not used for lua callbacks.
 /// @param  opts  Optional parameters.
-///               `on_lines`:       lua callback received on change.
-///               `on_changedtick`: lua callback received on changedtick
+///             - `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
+///             - `utf_sizes`:      include UTF-32 and UTF-16 size of
 ///                                 the replaced region.
 ///               See |api-buffer-updates-lua| for more information
 /// @param[out] err Error details, if any
diff --git a/src/nvim/api/tabpage.c b/src/nvim/api/tabpage.c
index b6830d9fcf..dd17bc03e5 100644
--- a/src/nvim/api/tabpage.c
+++ b/src/nvim/api/tabpage.c
@@ -14,7 +14,7 @@
 
 /// Gets the windows in a tabpage
 ///
-/// @param tabpage  Tabpage
+/// @param tabpage  Tabpage handle, or 0 for current tabpage
 /// @param[out] err Error details, if any
 /// @return List of windows in `tabpage`
 ArrayOf(Window) nvim_tabpage_list_wins(Tabpage tabpage, Error *err)
@@ -43,7 +43,7 @@ ArrayOf(Window) nvim_tabpage_list_wins(Tabpage tabpage, Error *err)
 
 /// Gets a tab-scoped (t:) variable
 ///
-/// @param tabpage  Tabpage handle
+/// @param tabpage  Tabpage handle, or 0 for current tabpage
 /// @param name     Variable name
 /// @param[out] err Error details, if any
 /// @return Variable value
@@ -61,7 +61,7 @@ Object nvim_tabpage_get_var(Tabpage tabpage, String name, Error *err)
 
 /// Sets a tab-scoped (t:) variable
 ///
-/// @param tabpage  Tabpage handle
+/// @param tabpage  Tabpage handle, or 0 for current tabpage
 /// @param name     Variable name
 /// @param value    Variable value
 /// @param[out] err Error details, if any
@@ -82,7 +82,7 @@ void nvim_tabpage_set_var(Tabpage tabpage,
 
 /// Removes a tab-scoped (t:) variable
 ///
-/// @param tabpage  Tabpage handle
+/// @param tabpage  Tabpage handle, or 0 for current tabpage
 /// @param name     Variable name
 /// @param[out] err Error details, if any
 void nvim_tabpage_del_var(Tabpage tabpage, String name, Error *err)
@@ -101,7 +101,7 @@ void nvim_tabpage_del_var(Tabpage tabpage, String name, Error *err)
 ///
 /// @deprecated
 ///
-/// @param tabpage  Tabpage handle
+/// @param tabpage  Tabpage handle, or 0 for current tabpage
 /// @param name     Variable name
 /// @param value    Variable value
 /// @param[out] err Error details, if any
@@ -124,7 +124,7 @@ Object tabpage_set_var(Tabpage tabpage, String name, Object value, Error *err)
 ///
 /// @deprecated
 ///
-/// @param tabpage  Tabpage handle
+/// @param tabpage  Tabpage handle, or 0 for current tabpage
 /// @param name     Variable name
 /// @param[out] err Error details, if any
 /// @return Old value
@@ -141,7 +141,7 @@ Object tabpage_del_var(Tabpage tabpage, String name, Error *err)
 
 /// Gets the current window in a tabpage
 ///
-/// @param tabpage  Tabpage handle
+/// @param tabpage  Tabpage handle, or 0 for current tabpage
 /// @param[out] err Error details, if any
 /// @return Window handle
 Window nvim_tabpage_get_win(Tabpage tabpage, Error *err)
@@ -169,7 +169,7 @@ Window nvim_tabpage_get_win(Tabpage tabpage, Error *err)
 
 /// Gets the tabpage number
 ///
-/// @param tabpage  Tabpage handle
+/// @param tabpage  Tabpage handle, or 0 for current tabpage
 /// @param[out] err Error details, if any
 /// @return Tabpage number
 Integer nvim_tabpage_get_number(Tabpage tabpage, Error *err)
@@ -187,7 +187,7 @@ Integer nvim_tabpage_get_number(Tabpage tabpage, Error *err)
 
 /// Checks if a tabpage is valid
 ///
-/// @param tabpage Tabpage handle
+/// @param tabpage  Tabpage handle, or 0 for current tabpage
 /// @return true if the tabpage is valid, false otherwise
 Boolean nvim_tabpage_is_valid(Tabpage tabpage)
   FUNC_API_SINCE(1)
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 60c58ff9a2..ce49045f24 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1059,11 +1059,11 @@ fail:
 ///      - "SE" south-east
 ///   - `height`: window height (in character cells). Minimum of 1.
 ///   - `width`: window width (in character cells). Minimum of 1.
-///   - 'bufpos': position float relative text inside the window `win` (only
-///               when relative="win"). Takes a tuple of [line, column] where
-///               both are zero-index. Note: `row` and `col` if present, still
-///               applies relative this positio. By default `row=1` and `col=0`
-///               is used (with default NW anchor), to make the float
+///   - '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.
diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
index 02670c0513..3e9f292eb9 100644
--- a/src/nvim/api/window.c
+++ b/src/nvim/api/window.c
@@ -22,7 +22,7 @@
 
 /// Gets the current buffer in a window
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param[out] err Error details, if any
 /// @return Buffer handle
 Buffer nvim_win_get_buf(Window window, Error *err)
@@ -39,7 +39,7 @@ Buffer nvim_win_get_buf(Window window, Error *err)
 
 /// Sets the current buffer in a window, without side-effects
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param buffer   Buffer handle
 /// @param[out] err Error details, if any
 void nvim_win_set_buf(Window window, Buffer buffer, Error *err)
@@ -78,7 +78,7 @@ void nvim_win_set_buf(Window window, Buffer buffer, Error *err)
 
 /// Gets the (1,0)-indexed cursor position in the window. |api-indexing|
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param[out] err Error details, if any
 /// @return (row, col) tuple
 ArrayOf(Integer, 2) nvim_win_get_cursor(Window window, Error *err)
@@ -97,7 +97,7 @@ ArrayOf(Integer, 2) nvim_win_get_cursor(Window window, Error *err)
 
 /// Sets the (1,0)-indexed cursor position in the window. |api-indexing|
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param pos      (row, col) tuple representing the new position
 /// @param[out] err Error details, if any
 void nvim_win_set_cursor(Window window, ArrayOf(Integer, 2) pos, Error *err)
@@ -147,7 +147,7 @@ void nvim_win_set_cursor(Window window, ArrayOf(Integer, 2) pos, Error *err)
 
 /// Gets the window height
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param[out] err Error details, if any
 /// @return Height as a count of rows
 Integer nvim_win_get_height(Window window, Error *err)
@@ -165,7 +165,7 @@ Integer nvim_win_get_height(Window window, Error *err)
 /// Sets the window height. This will only succeed if the screen is split
 /// horizontally.
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param height   Height as a count of rows
 /// @param[out] err Error details, if any
 void nvim_win_set_height(Window window, Integer height, Error *err)
@@ -192,7 +192,7 @@ void nvim_win_set_height(Window window, Integer height, Error *err)
 
 /// Gets the window width
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param[out] err Error details, if any
 /// @return Width as a count of columns
 Integer nvim_win_get_width(Window window, Error *err)
@@ -210,7 +210,7 @@ Integer nvim_win_get_width(Window window, Error *err)
 /// Sets the window width. This will only succeed if the screen is split
 /// vertically.
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param width    Width as a count of columns
 /// @param[out] err Error details, if any
 void nvim_win_set_width(Window window, Integer width, Error *err)
@@ -237,7 +237,7 @@ void nvim_win_set_width(Window window, Integer width, Error *err)
 
 /// Gets a window-scoped (w:) variable
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param name     Variable name
 /// @param[out] err Error details, if any
 /// @return Variable value
@@ -255,7 +255,7 @@ Object nvim_win_get_var(Window window, String name, Error *err)
 
 /// Sets a window-scoped (w:) variable
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param name     Variable name
 /// @param value    Variable value
 /// @param[out] err Error details, if any
@@ -273,7 +273,7 @@ void nvim_win_set_var(Window window, String name, Object value, Error *err)
 
 /// Removes a window-scoped (w:) variable
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param name     Variable name
 /// @param[out] err Error details, if any
 void nvim_win_del_var(Window window, String name, Error *err)
@@ -292,7 +292,7 @@ void nvim_win_del_var(Window window, String name, Error *err)
 ///
 /// @deprecated
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param name     Variable name
 /// @param value    Variable value
 /// @param[out] err Error details, if any
@@ -315,7 +315,7 @@ Object window_set_var(Window window, String name, Object value, Error *err)
 ///
 /// @deprecated
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param name     variable name
 /// @param[out] err Error details, if any
 /// @return Old value
@@ -332,7 +332,7 @@ Object window_del_var(Window window, String name, Error *err)
 
 /// Gets a window option value
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param name     Option name
 /// @param[out] err Error details, if any
 /// @return Option value
@@ -352,7 +352,7 @@ Object nvim_win_get_option(Window window, String name, Error *err)
 /// works if there's a global fallback)
 ///
 /// @param channel_id
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param name     Option name
 /// @param value    Option value
 /// @param[out] err Error details, if any
@@ -371,7 +371,7 @@ void nvim_win_set_option(uint64_t channel_id, Window window,
 
 /// Gets the window position in display cells. First position is zero.
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param[out] err Error details, if any
 /// @return (row, col) tuple with the window position
 ArrayOf(Integer, 2) nvim_win_get_position(Window window, Error *err)
@@ -390,7 +390,7 @@ ArrayOf(Integer, 2) nvim_win_get_position(Window window, Error *err)
 
 /// Gets the window tabpage
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param[out] err Error details, if any
 /// @return Tabpage that contains the window
 Tabpage nvim_win_get_tabpage(Window window, Error *err)
@@ -408,7 +408,7 @@ Tabpage nvim_win_get_tabpage(Window window, Error *err)
 
 /// Gets the window number
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param[out] err Error details, if any
 /// @return Window number
 Integer nvim_win_get_number(Window window, Error *err)
@@ -429,7 +429,7 @@ Integer nvim_win_get_number(Window window, Error *err)
 
 /// Checks if a window is valid
 ///
-/// @param window Window handle
+/// @param window Window handle, or 0 for current window
 /// @return true if the window is valid, false otherwise
 Boolean nvim_win_is_valid(Window window)
   FUNC_API_SINCE(1)
@@ -451,7 +451,7 @@ Boolean nvim_win_is_valid(Window window)
 /// changed. The following restriction apply: `row`, `col` and `relative`
 /// must be reconfigured together. Only changing a subset of these is an error.
 ///
-/// @param      window  Window handle
+/// @param      window  Window handle, or 0 for current window
 /// @param      config  Dictionary of window configuration
 /// @param[out] err     Error details, if any
 void nvim_win_set_config(Window window, Dictionary config, Error *err)
@@ -490,7 +490,7 @@ void nvim_win_set_config(Window window, Dictionary config, Error *err)
 ///
 /// `relative` will be an empty string for normal windows.
 ///
-/// @param      window Window handle
+/// @param      window Window handle, or 0 for current window
 /// @param[out] err Error details, if any
 /// @return     Window configuration
 Dictionary nvim_win_get_config(Window window, Error *err)
@@ -537,7 +537,7 @@ Dictionary nvim_win_get_config(Window window, Error *err)
 
 /// Closes the window (like |:close| with a |window-ID|).
 ///
-/// @param window   Window handle
+/// @param window   Window handle, or 0 for current window
 /// @param 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 not set.
diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua
index f0f24e4d16..9149285efd 100644
--- a/src/nvim/lua/vim.lua
+++ b/src/nvim/lua/vim.lua
@@ -215,9 +215,11 @@ paste = (function()
   end
 end)()
 
---- Defers the wrapped callback until the Nvim API is safe to call.
+--- Defers callback `cb` until the Nvim API is safe to call.
 ---
---@see |vim-loop-callbacks|
+---@see |lua-loop-callbacks|
+---@see |vim.schedule()|
+---@see |vim.in_fast_event()|
 local function schedule_wrap(cb)
   return (function (...)
     local args = {...}