Merge #10986 'doc'

10 files changed, 202 insertions, 183 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 21cc114598..18129e8c39 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -408,34 +408,26 @@ Example using the API from Vimscript: >
 ==============================================================================
 Floating windows						 *api-floatwin*
 
-Nvim supports floating windows, windows that are displayed on top of ordinary
-windows.  This is useful to implement simple widgets, such as tooltips
-displaying information next to cursor text. Floating windows are fully
-functional buffer windows and support user editing. They support the standard
-|api-window| calls and almost all window options (with some exceptions such as
-'statusline' is not supported currently).
-
-Floating windows are created either by |nvim_open_win()| to open a new window,
-or |nvim_win_set_config()| to reconfigure a normal window into a float.
-Currently the position can either be grid coordinates relative to the top-left
-of some window, or a position relative to the current window cursor.  The
-parameters for positioning are described in detail at |nvim_open_win()|.
-
-|nvim_open_win()| assumes an existing buffer to display in the window. To create
-a scratch buffer for the float, |nvim_create_buf()| can be used. The text in
-the buffer can be highlighted using standard functionality, such as syntax
-highlighting, or |api-highlights|.
-
-By default, floats will use |hl-NormalFloat| as normal highlight, which
-links to |hl-Pmenu| in the builtin color scheme. The 'winhighlight' option can
-be used to override it. Currently, floating windows don't support any visual
-decorations like a border or additional widgets like scrollbar. By default,
-floats will inherit options from the current window. This is not always
-useful for some options, like 'number'. Use `style='minimal'` flag to
-|nvim_open_win()| to disable many UI features that are unwanted for a simple
-float, like end-of-buffer region or special columns.
-
-Here is an example for creating a float with scratch buffer: >
+Floating windows ("floats") are displayed on top of normal windows.  This is
+useful to implement simple widgets, such as tooltips displayed next to the
+cursor. Floats are fully functional windows supporting user editing, common
+|api-window| calls, and most window options (except 'statusline').
+
+Two ways to create a floating window:
+- |nvim_open_win()| creates a new window (needs a buffer, see |nvim_create_buf()|)
+- |nvim_win_set_config()| reconfigures a normal window into a float
+
+To close it use |nvim_win_close()| or a command such as |:close|.
+
+Buffer text can be highlighted by typical mechanisms (syntax highlighting,
+|api-highlights|). The |hl-NormalFloat| group highlights normal text;
+'winhighlight' can be used as usual to override groups locally. Floats inherit
+options from the current window; specify `style=minimal` in |nvim_open_win()|
+to disable various visual features such as the 'number' column.
+
+Currently, floating windows don't support widgets like border or scrollbar.
+
+Example: create a float with scratch buffer: >
 
     let buf = nvim_create_buf(v:false, v:true)
     call nvim_buf_set_lines(buf, 0, -1, v:true, ["test", "text"])
@@ -445,7 +437,6 @@ Here is an example for creating a float with scratch buffer: >
     " optional: change highlight, otherwise Pmenu is used
     call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight')
 >
-To close the float, |nvim_win_close()| can be used.
 
 ==============================================================================
 Global Functions                                                  *api-global*
@@ -604,18 +595,18 @@ nvim_eval({expr})                                                *nvim_eval()*
                     Evaluation result or expanded object
 
 nvim_execute_lua({code}, {args})                          *nvim_execute_lua()*
-                Execute lua code. Parameters (if any) are available as `...`
+                Execute Lua code. Parameters (if any) are available as `...`
                 inside the chunk. The chunk can return a value.
 
                 Only statements are executed. To evaluate an expression,
                 prefix it with `return` : return my_function(...)
 
                 Parameters: ~
-                    {code}  lua code to execute
+                    {code}  Lua code to execute
                     {args}  Arguments to the code
 
                 Return: ~
-                    Return value of lua code if present or NIL.
+                    Return value of Lua code if present or NIL.
 
 nvim_call_function({fn}, {args})                        *nvim_call_function()*
                 Calls a VimL function with the given arguments.
@@ -830,74 +821,77 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                 Exactly one of `external` and `relative` must be specified.
                 The `width` and `height` of the new window must be specified.
 
-                With editor positioning row=0, col=0 refers to the top-left
-                corner of the screen-grid and row=Lines-1, Columns-1 refers to
-                the bottom-right corner. Floating point values are allowed,
-                but the builtin implementation (used by TUI and GUIs without
-                multigrid support) will always round down to nearest integer.
+                With relative=editor (row=0,col=0) refers to the top-left
+                corner of the screen-grid and (row=Lines-1,col=Columns-1)
+                refers to the bottom-right corner. Fractional values are
+                allowed, but the builtin implementation (used by non-multigrid
+                UIs) will always round down to nearest integer.
 
                 Out-of-bounds values, and configurations that make the float
                 not fit inside the main editor, are allowed. The builtin
-                implementation will truncate values so floats are completely
-                within the main screen grid. External GUIs could let floats
-                hover outside of the main window like a tooltip, but this
-                should not be used to specify arbitrary WM screen positions.
-
-                Parameters: ~
-                    {buffer}  handle of buffer to be displayed in the window
-                    {enter}   whether the window should be entered (made the
-                              current window)
-                    {config}  Dictionary for the window configuration accepts
-                              these keys:
-                              •  `relative` : If set, the window becomes a floating
-                                window. The window will be placed with row,col
-                                coordinates relative to one of the following:
-                                • "editor" the global editor grid
-                                • "win" a window. Use `win` to specify a
-                                  window id, or the current window will be
-                                  used by default.
-                                • "cursor" the cursor position in current
-                                  window.
-
-                              • `win` : When using relative='win', window id
-                                of the window where the position is defined.
-                              •  `anchor` : The corner of the float that the row,col
-                                position defines:
-                                • "NW" north-west (default)
-                                • "NE" north-east
-                                • "SW" south-west
-                                • "SE" south-east
-
-                              • `height` : window height (in character cells).
+                implementation truncates values so floats are fully within the
+                main screen grid. External GUIs could let floats hover outside
+                of the main window like a tooltip, but this should not be used
+                to specify arbitrary WM screen positions.
+
+                Example (Lua): window-relative float >
+                    vim.api.nvim_open_win(0, false,
+                      {relative='win', row=3, col=3, width=12, height=3})
+<
+
+                Example (Lua): buffer-relative float (travels as buffer is
+                scrolled) >
+                    vim.api.nvim_open_win(0, false,
+                      {relative='win', width=12, height=3, bufpos={100,10}})
+<
+
+                Parameters: ~
+                    {buffer}  Buffer to display, or 0 for current buffer
+                    {enter}   Enter the window (make it the current window)
+                    {config}  Map defining the window configuration. Keys:
+                              •  `relative` : Sets the window layout to "floating", placed
+                                at (row,col) coordinates relative to one of:
+                                • "editor" The global editor grid
+                                • "win" Window given by the `win` field, or
+                                  current window by default.
+                                • "cursor" Cursor position in current window.
+
+                              • `win` : |window-ID| for relative="win".
+                              •  `anchor` : Decides which corner of the float to place
+                                at (row,col):
+                                • "NW" northwest (default)
+                                • "NE" northeast
+                                • "SW" southwest
+                                • "SE" southeast
+
+                              • `width` : Window width (in character cells).
                                 Minimum of 1.
-                              • `width` : window width (in character cells).
+                              • `height` : Window height (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
-                                used as unit. Can be floating point.
-                              • `focusable` : Whether window can be focused by
-                                wincmds and mouse events. Defaults to true.
-                                Even if set to false, the window can still be
-                                entered using |nvim_set_current_win()| API
-                                call.
+                              • `bufpos` : Places float relative to buffer
+                                text (only when relative="win"). Takes a tuple
+                                of zero-indexed [line, column]. `row` and
+                                `col` if given are applied relative to this
+                                position, else they default to `row=1` and
+                                `col=0` (thus like a tooltip near the buffer
+                                text).
+                              • `row` : Row position in units of "screen cell
+                                height", may be fractional.
+                              • `col` : Column position in units of "screen
+                                cell width", may be fractional.
+                              • `focusable` : Enable focus by user actions
+                                (wincmds, mouse events). Defaults to true.
+                                Non-focusable windows can be entered by
+                                |nvim_set_current_win()|.
                               • `external` : GUI should display the window as
                                 an external top-level window. Currently
                                 accepts no other positioning configuration
                                 together with this.
-                              •  `style` : Configure the apparance of the window.
+                              •  `style` : Configure the appearance of the window.
                                 Currently only takes one non-empty value:
                                 • "minimal" Nvim will display the window with
                                   many UI options disabled. This is useful
-                                  when displaing a temporary float where the
+                                  when displaying a temporary float where the
                                   text should not be edited. Disables
                                   'number', 'relativenumber', 'cursorline',
                                   'cursorcolumn', 'foldcolumn', 'spell' and
@@ -906,8 +900,6 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                                   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.
 
                 Return: ~
                     Window handle, or 0 on error
@@ -1985,35 +1977,35 @@ nvim_win_is_valid({window})                              *nvim_win_is_valid()*
                     true if the window is valid, false otherwise
 
 nvim_win_set_config({window}, {config})                *nvim_win_set_config()*
-                Configure window position. Currently this is only used to
-                configure floating and external windows (including changing a
-                split window to these types).
-
-                See documentation at |nvim_open_win()|, for the meaning of
-                parameters.
+                Configures window layout. Currently only for floating and
+                external windows (including changing a split window to those
+                layouts).
 
                 When reconfiguring a floating window, absent option keys will
-                not be changed. The following restriction apply: `row` , `col`
-                and `relative` must be reconfigured together. Only changing a
-                subset of these is an error.
+                not be changed. `row` / `col` and `relative` must be
+                reconfigured together.
 
                 Parameters: ~
                     {window}  Window handle, or 0 for current window
-                    {config}  Dictionary of window configuration
+                    {config}  Map defining the window configuration, see
+                              |nvim_open_win()|
+
+                See also: ~
+                    |nvim_open_win()|
 
 nvim_win_get_config({window})                          *nvim_win_get_config()*
-                Return window configuration.
+                Gets window configuration.
 
-                Return a dictionary containing the same config that can be
-                given to |nvim_open_win()|.
+                The returned value may be given to |nvim_open_win()|.
 
-                `relative` will be an empty string for normal windows.
+                `relative` is empty for normal windows.
 
                 Parameters: ~
                     {window}  Window handle, or 0 for current window
 
                 Return: ~
-                    Window configuration
+                    Map defining the window configuration, see
+                    |nvim_open_win()|
 
 nvim_win_close({window}, {force})                           *nvim_win_close()*
                 Closes the window (like |:close| with a |window-ID|).
@@ -2136,4 +2128,11 @@ nvim_ui_try_resize_grid({grid}, {width}, {height})
                     {width}   The new requested width.
                     {height}  The new requested height.
 
+nvim_ui_pum_set_height({height})                    *nvim_ui_pum_set_height()*
+                Tells Nvim the number of elements displaying in the popumenu,
+                to decide <PageUp> and <PageDown> movement.
+
+                Parameters: ~
+                    {height}  Popupmenu height, must be greater than zero.
+
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 53a5f247f9..f845268333 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -2952,9 +2952,9 @@ char2nr({expr} [, {utf8}])					*char2nr()*
 			char2nr("ABC")		returns 65
 			char2nr("á")		returns 225
 			char2nr("á"[0])		returns 195
+			char2nr("\<M-x>")	returns 128
 <		Non-ASCII characters are always treated as UTF-8 characters.
-		{utf8} has no effect, and exists only for
-		backwards-compatibility.
+		{utf8} is ignored, it exists only for backwards-compatibility.
 		A combining character is a separate character.
 		|nr2char()| does the opposite.
 
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
index 11950da91e..aa2d0a03c6 100644
--- a/runtime/doc/if_lua.txt
+++ b/runtime/doc/if_lua.txt
@@ -525,6 +525,7 @@ inspect({object}, {options})                                   *vim.inspect()*
 
                 See also: ~
                     https://github.com/kikito/inspect.lua
+                    https://github.com/mpeterv/vinspect
 
 paste({lines}, {phase})                                          *vim.paste()*
                 Paste handler, invoked by |nvim_paste()| when a conforming UI
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index aebb58889a..be9e25113a 100644
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@@ -847,6 +847,10 @@ tag		char	      note action in Normal mode	~
 				   position the cursor at the start (left
 				   side) of the screen
 |zt|		zt		   redraw, cursor line at top of window
+|zuw|		zuw		   undo |zw|
+|zug|		zug		   undo |zg|
+|zuW|		zuW		   undo |zW|
+|zuG|		zuG		   undo |zG|
 |zv|		zv		   open enough folds to view the cursor line
 |zw|		zw		   mark word as wrong (bad) spelled word
 |zx|		zx		   re-apply 'foldlevel' and do "zv"
@@ -1078,10 +1082,17 @@ tag		command		action in Command-line editing mode	~
 |c_<Insert>|	<Insert>	toggle insert/overstrike mode
 |c_<LeftMouse>|	<LeftMouse>	cursor at mouse click
 
+==============================================================================
+5. Terminal mode				*terminal-mode-index*
+
+In a |terminal| buffer all keys except |CTRL-\_CTRL-N| are forwarded to the
+terminal job.  Use CTRL-\_CTRL-N to go to Normal mode.
+
+
 You found it, Arthur!				*holy-grail*
 
 ==============================================================================
-5. EX commands					*ex-cmd-index* *:index*
+6. EX commands					*ex-cmd-index* *:index*
 
 This is a brief but complete listing of all the ":" commands, without
 mentioning any arguments.  The optional part of the command name is inside [].
@@ -1089,10 +1100,13 @@ The commands are sorted on the non-optional part of their name.
 
 tag		command		action ~
 ------------------------------------------------------------------------------
+|:|		:		nothing
+|:range|	:{range}	go to last line in {range}
 |:!|		:!		filter lines or execute an external command
 |:!!|		:!!		repeat last ":!" command
 |:#|		:#		same as ":number"
 |:&|		:&		repeat last ":substitute"
+|:star|		:*		execute contents of a register
 |:<|		:<		shift lines one 'shiftwidth' left
 |:=|		:=		print the cursor line number
 |:>|		:>		shift lines one 'shiftwidth' right
@@ -1160,7 +1174,7 @@ tag		command		action ~
 |:cclose|	:ccl[ose]	close quickfix window
 |:cd|		:cd		change directory
 |:cdo|		:cdo		execute command in each valid error list entry
-|:cfdo|		:cfdo		execute command in each file in error list
+|:cfdo|		:cfd[o]		execute command in each file in error list
 |:center|	:ce[nter]	format lines at the center
 |:cexpr|	:cex[pr]	read errors from expr and jump to first
 |:cfile|	:cf[ile]	read file with error messages and jump to first
@@ -1361,9 +1375,9 @@ tag		command		action ~
 |:ltag|		:lt[ag]		jump to tag and add matching tags to the
 				location list
 |:lunmap|	:lu[nmap]	like ":unmap!" but includes Lang-Arg mode
-|:lua|		:lua		execute Lua command
+|:lua|		:lua		execute |Lua| command
 |:luado|	:luad[o]	execute Lua command for each line
-|:luafile|	:luaf[ile]	execute Lua script file
+|:luafile|	:luaf[ile]	execute |Lua| script file
 |:lvimgrep|	:lv[imgrep]	search for pattern in files
 |:lvimgrepadd|	:lvimgrepa[dd]	like :vimgrep, but append to current list
 |:lwindow|	:lw[indow]	open or close location window
@@ -1402,7 +1416,7 @@ tag		command		action ~
 |:number|	:nu[mber]	print lines with line number
 |:nunmap|	:nun[map]	like ":unmap" but for Normal mode
 |:nunmenu|	:nunme[nu]	remove menu for Normal mode
-|:oldfiles|	:o[ldfiles]	list files that have marks in the ShaDa file
+|:oldfiles|	:ol[dfiles]	list files that have marks in the |shada| file
 |:omap|		:om[ap]		like ":map" but for Operator-pending mode
 |:omapclear|	:omapc[lear]	remove all mappings for Operator-pending mode
 |:omenu|	:ome[nu]	add menu for Operator-pending mode
@@ -1467,7 +1481,10 @@ tag		command		action ~
 |:rewind|	:rew[ind]	go to the first file in the argument list
 |:right|	:ri[ght]	right align text
 |:rightbelow|	:rightb[elow]	make split window appear right or below
-|:rshada|	:rsh[ada]	read from ShaDa file
+|:rshada|	:rsh[ada]	read from |shada| file
+|:ruby|		:rub[y]		execute Ruby command
+|:rubydo|	:rubyd[o]	execute Ruby command for each line
+|:rubyfile|	:rubyf[ile]	execute Ruby script file
 |:rundo|	:rund[o]	read undo information from a file
 |:runtime|	:ru[ntime]	source vim scripts in 'runtimepath'
 |:substitute|	:s[ubstitute]	find and replace text
@@ -1570,6 +1587,8 @@ tag		command		action ~
 |:tab|		:tab		create new tab when opening new window
 |:tag|		:ta[g]		jump to tag
 |:tags|		:tags		show the contents of the tag stack
+|:tcd|		:tcd		change directory for tab page
+|:tchdir|	:tch[dir]	change directory for tab page
 |:terminal|	:te[rminal]	open a terminal buffer
 |:tfirst|	:tf[irst]	jump to first matching tag
 |:throw|	:th[row]	throw an exception
diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c
index 9ff2a529ae..ada26a2a07 100644
--- a/src/nvim/api/ui.c
+++ b/src/nvim/api/ui.c
@@ -314,14 +314,11 @@ void nvim_ui_try_resize_grid(uint64_t channel_id, Integer grid, Integer width,
   ui_grid_resize((handle_T)grid, (int)width, (int)height, err);
 }
 
-/// Tell Nvim the number of element displayed in popumenu. The amount of
-/// movement by <PageUp> or <PageDown> is determined by the value set by this.
-///
-/// If the ext_popupmenu option is false or the height is 0 or less, fails
-/// with error.
+/// Tells Nvim the number of elements displaying in the popumenu, to decide
+/// <PageUp> and <PageDown> movement.
 ///
 /// @param channel_id
-/// @param height  The popupmenu height.
+/// @param height  Popupmenu height, must be greater than zero.
 /// @param[out] err Error details, if any
 void nvim_ui_pum_set_height(uint64_t channel_id, Integer height, Error *err)
   FUNC_API_SINCE(6) FUNC_API_REMOTE_ONLY
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index ce49045f24..147830493a 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -437,18 +437,18 @@ Object nvim_eval(String expr, Error *err)
   return rv;
 }
 
-/// Execute lua code. Parameters (if any) are available as `...` inside the
+/// Execute Lua code. Parameters (if any) are available as `...` inside the
 /// chunk. The chunk can return a value.
 ///
 /// Only statements are executed. To evaluate an expression, prefix it
 /// with `return`: return my_function(...)
 ///
-/// @param code       lua code to execute
+/// @param code       Lua code to execute
 /// @param args       Arguments to the code
 /// @param[out] err   Details of an error encountered while parsing
-///                   or executing the lua code.
+///                   or executing the Lua code.
 ///
-/// @return           Return value of lua code if present or NIL.
+/// @return           Return value of Lua code if present or NIL.
 Object nvim_execute_lua(String code, Array args, Error *err)
   FUNC_API_SINCE(3) FUNC_API_REMOTE_ONLY
 {
@@ -1028,66 +1028,70 @@ fail:
 /// Exactly one of `external` and `relative` must be specified. The `width` and
 /// `height` of the new window must be specified.
 ///
-/// With editor positioning row=0, col=0 refers to the top-left corner of the
-/// screen-grid and row=Lines-1, Columns-1 refers to the bottom-right corner.
-/// Floating point values are allowed, but the builtin implementation (used by
-/// TUI and GUIs without multigrid support) will always round down to nearest
-/// integer.
+/// With relative=editor (row=0,col=0) refers to the top-left corner of the
+/// screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right
+/// corner. Fractional values are allowed, but the builtin implementation
+/// (used by non-multigrid UIs) will always round down to nearest integer.
 ///
 /// Out-of-bounds values, and configurations that make the float not fit inside
-/// the main editor, are allowed. The builtin implementation will truncate
-/// values so floats are completely within the main screen grid. External GUIs
+/// the main editor, are allowed. The builtin implementation truncates values
+/// so floats are fully within the main screen grid. External GUIs
 /// could let floats hover outside of the main window like a tooltip, but
 /// this should not be used to specify arbitrary WM screen positions.
 ///
-/// @param buffer handle of buffer to be displayed in the window
-/// @param enter  whether the window should be entered (made the current window)
-/// @param config Dictionary for the window configuration accepts these keys:
-///   - `relative`: If set, the window becomes a floating window. The window
-///       will be placed with row,col coordinates relative to one of the
-///       following:
-///      - "editor" the global editor grid
-///      - "win"    a window. Use `win` to specify a window id,
-///                 or the current window will be used by default.
-///      - "cursor" the cursor position in current window.
-///   - `win`: When using relative='win', window id of the window where the
-///       position is defined.
-///   - `anchor`: The corner of the float that the row,col position defines:
-///      - "NW" north-west (default)
-///      - "NE" north-east
-///      - "SW" south-west
-///      - "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 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 used as unit. Can be
-///       floating point.
-///   - `focusable`: Whether window can be focused by wincmds and
-///       mouse events. Defaults to true. Even if set to false, the window
-///       can still be entered using |nvim_set_current_win()| API call.
+/// Example (Lua): window-relative float
+/// <pre>
+///     vim.api.nvim_open_win(0, false,
+///       {relative='win', row=3, col=3, width=12, height=3})
+/// </pre>
+///
+/// Example (Lua): buffer-relative float (travels as buffer is scrolled)
+/// <pre>
+///     vim.api.nvim_open_win(0, false,
+///       {relative='win', width=12, height=3, bufpos={100,10}})
+/// </pre>
+///
+/// @param buffer Buffer to display, or 0 for current buffer
+/// @param enter  Enter the window (make it the current window)
+/// @param config Map defining the window configuration. Keys:
+///   - `relative`: Sets the window layout to "floating", placed at (row,col)
+///                 coordinates relative to one of:
+///      - "editor" The global editor grid
+///      - "win"    Window given by the `win` field, or current window by
+///                 default.
+///      - "cursor" Cursor position in current window.
+///   - `win`: |window-ID| for relative="win".
+///   - `anchor`: Decides which corner of the float to place at (row,col):
+///      - "NW" northwest (default)
+///      - "NE" northeast
+///      - "SW" southwest
+///      - "SE" southeast
+///   - `width`: Window width (in character cells). Minimum of 1.
+///   - `height`: Window height (in character cells). Minimum of 1.
+///   - `bufpos`: Places float relative to buffer text (only when
+///               relative="win"). Takes a tuple of zero-indexed [line, column].
+///               `row` and `col` if given are applied relative to this
+///               position, else they default to `row=1` and `col=0`
+///               (thus like a tooltip near the buffer text).
+///   - `row`: Row position in units of "screen cell height", may be fractional.
+///   - `col`: Column position in units of "screen cell width", may be
+///            fractional.
+///   - `focusable`: Enable focus by user actions (wincmds, mouse events).
+///       Defaults to true. Non-focusable windows can be entered by
+///       |nvim_set_current_win()|.
 ///   - `external`: GUI should display the window as an external
 ///       top-level window. Currently accepts no other positioning
 ///       configuration together with this.
-///   - `style`: Configure the apparance of the window. Currently only takes
+///   - `style`: Configure the appearance of the window. Currently only takes
 ///       one non-empty value:
 ///       - "minimal"  Nvim will display the window with many UI options
-///                    disabled. This is useful when displaing a temporary
+///                    disabled. This is useful when displaying a temporary
 ///                    float where the text should not be edited. Disables
 ///                    'number', 'relativenumber', 'cursorline', '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.
 /// @param[out] err Error details, if any
 ///
 /// @return Window handle, or 0 on error
diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
index 3e9f292eb9..ba43bc6cb2 100644
--- a/src/nvim/api/window.c
+++ b/src/nvim/api/window.c
@@ -441,18 +441,17 @@ Boolean nvim_win_is_valid(Window window)
 }
 
 
-/// Configure window position. Currently this is only used to configure
-/// floating and external windows (including changing a split window to these
-/// types).
-///
-/// See documentation at |nvim_open_win()|, for the meaning of parameters.
+/// Configures window layout. Currently only for floating and external windows
+/// (including changing a split window to those layouts).
 ///
 /// When reconfiguring a floating window, absent option keys will not be
-/// changed. The following restriction apply: `row`, `col` and `relative`
-/// must be reconfigured together. Only changing a subset of these is an error.
+/// changed.  `row`/`col` and `relative` must be reconfigured together.
+///
+/// @see |nvim_open_win()|
 ///
 /// @param      window  Window handle, or 0 for current window
-/// @param      config  Dictionary of window configuration
+/// @param      config  Map defining the window configuration,
+///                     see |nvim_open_win()|
 /// @param[out] err     Error details, if any
 void nvim_win_set_config(Window window, Dictionary config, Error *err)
   FUNC_API_SINCE(6)
@@ -483,16 +482,15 @@ void nvim_win_set_config(Window window, Dictionary config, Error *err)
   }
 }
 
-/// Return window configuration.
+/// Gets window configuration.
 ///
-/// Return a dictionary containing the same config that can be given to
-/// |nvim_open_win()|.
+/// The returned value may be given to |nvim_open_win()|.
 ///
-/// `relative` will be an empty string for normal windows.
+/// `relative` is empty for normal windows.
 ///
 /// @param      window Window handle, or 0 for current window
 /// @param[out] err Error details, if any
-/// @return     Window configuration
+/// @return     Map defining the window configuration, see |nvim_open_win()|
 Dictionary nvim_win_get_config(Window window, Error *err)
   FUNC_API_SINCE(6)
 {
diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua
index 9149285efd..f8e52d31c9 100644
--- a/src/nvim/lua/vim.lua
+++ b/src/nvim/lua/vim.lua
@@ -157,6 +157,7 @@ end
 --- Return a human-readable representation of the given object.
 ---
 --@see https://github.com/kikito/inspect.lua
+--@see https://github.com/mpeterv/vinspect
 local function inspect(object, options)  -- luacheck: no unused
   error(object, options)  -- Stub for gen_vimdoc.py
 end
diff --git a/src/nvim/window.c b/src/nvim/window.c
index 315b5ef759..7b6083cf29 100644
--- a/src/nvim/window.c
+++ b/src/nvim/window.c
@@ -969,8 +969,8 @@ bool parse_float_config(Dictionary config, FloatConfig *fconfig, bool reconf,
   }
 
   if (has_relative != has_row || has_row != has_col) {
-    api_set_error(err, kErrorTypeValidation, "All of 'relative', 'row', and "
-                  "'col' has to be specified at once");
+    api_set_error(err, kErrorTypeValidation,
+                  "'relative' requires 'row'/'col' or 'bufpos'");
     return false;
   }
   return true;
diff --git a/test/functional/ui/float_spec.lua b/test/functional/ui/float_spec.lua
index f6c18ba841..dbaf6f802b 100644
--- a/test/functional/ui/float_spec.lua
+++ b/test/functional/ui/float_spec.lua
@@ -646,7 +646,7 @@ describe('floating windows', function()
          pcall_err(meths.open_win,buf, false, {width=20,height=2,relative='shell',row=0,col=0}))
       eq("Invalid value of 'anchor' key",
          pcall_err(meths.open_win,buf, false, {width=20,height=2,relative='editor',row=0,col=0,anchor='bottom'}))
-      eq("All of 'relative', 'row', and 'col' has to be specified at once",
+      eq("'relative' requires 'row'/'col' or 'bufpos'",
          pcall_err(meths.open_win,buf, false, {width=20,height=2,relative='editor'}))
       eq("'width' key must be a positive Integer",
          pcall_err(meths.open_win,buf, false, {width=-1,height=2,relative='editor'}))