Merge #10546 'doc'

6 files changed, 52 insertions, 46 deletions

diff --git a/src/nvim/README.md b/src/nvim/README.md
index 35ca2944e9..3f7c05757a 100644
--- a/src/nvim/README.md
+++ b/src/nvim/README.md
@@ -62,6 +62,8 @@ Configure the sanitizer(s) via these environment variables:
 
     # Change to detect_leaks=1 to detect memory leaks (slower).
     export ASAN_OPTIONS="detect_leaks=0:log_path=$HOME/logs/asan"
+    # Show backtraces in the logs.
+    export UBSAN_OPTIONS=print_stacktrace=1
     export MSAN_OPTIONS="log_path=${HOME}/logs/tsan"
     export TSAN_OPTIONS="log_path=${HOME}/logs/tsan"
 
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 690497159a..3e1209d1b1 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
@@ -183,6 +183,8 @@ error:
 
 /// Deactivates buffer-update events on the channel.
 ///
+/// For Lua callbacks see |api-lua-detach|.
+///
 /// @param channel_id
 /// @param buffer Buffer handle, or 0 for current buffer
 /// @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 27344fc093..ce49045f24 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1019,7 +1019,7 @@ fail:
 ///
 /// 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 internally or by external
+/// 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.
 ///
@@ -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.
@@ -1416,9 +1416,9 @@ Dictionary nvim_get_color_map(void)
 /// Gets a map of the current editor state.
 ///
 /// @param  types  Context types ("regs", "jumps", "buflist", "gvars", ...)
-///                to gather, or NIL for all.
+///                to gather, or NIL for all (see |context-types|).
 ///
-/// @return map of global context
+/// @return map of global |context|.
 Dictionary nvim_get_context(Array types)
   FUNC_API_SINCE(6)
 {
@@ -1453,9 +1453,9 @@ Dictionary nvim_get_context(Array types)
   return dict;
 }
 
-/// Sets the current editor state to that in given context dictionary.
+/// Sets the current editor state from the given |context| map.
 ///
-/// @param ctx_dict  Context dictionary.
+/// @param  dict  |Context| map.
 Object nvim_load_context(Dictionary dict)
   FUNC_API_SINCE(6)
 {
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 = {...}