api: update doc

runtime/doc/api.txt

@@ -245,10 +245,10 @@ functional buffer windows and support user editing. They support the standard
 'statusline' is not supported currently).
 
 Floating windows are created either by |nvim_open_win()| to open a new window,
-or |nvim_win_config()| to reconfigure a normal window into a float. Currently
+or |nvim_win_set_config()| to reconfigure a normal window into a float.
-the position can either be grid coordinates relative the top-left of some
+Currently the position can either be grid coordinates relative the top-left of
-window, or a position relative to the current window cursor.  The parameters
+some window, or a position relative to the current window cursor.  The
-for positioning are described in detail at |nvim_open_win()| help.
+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_buffer()| can be used. The text in
@@ -264,8 +264,9 @@ Here is an example for creating 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"])
-    let opts = {'relative': 'cursor', 'col':0, 'row':1, 'anchor': 'NW'}
+    let opts = {'relative': 'cursor', 'width': 10, 'height': 2, 'col': 0,
-    let win =  nvim_open_win(buf, 0, 10, 2, opts)
+        \ 'row': 1, 'anchor': 'NW'}
+    let win = nvim_open_win(buf, 0, opts)
     " optional: change highlight, otherwise Pmenu is used
     call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight')
 >
@@ -624,8 +625,7 @@ nvim_create_buf({listed}, {scratch})                       *nvim_create_buf()*
                 Return: ~
                     Buffer handle, or 0 on error
 
-                                                             *nvim_open_win()*
+nvim_open_win({buffer}, {enter}, {options})                  *nvim_open_win()*
-nvim_open_win({buffer}, {enter}, {width}, {height}, {options})
                 Open a new window.
 
                 Currently this is used to open floating and external windows.
@@ -643,8 +643,6 @@ nvim_open_win({buffer}, {enter}, {width}, {height}, {options})
                     {buffer}   handle of buffer to be displayed in the window
                     {enter}    whether the window should be entered (made the
                                current window)
-                    {width}    width of window (in character cells)
-                    {height}   height of window (in character cells)
                     {options}  dict of options for configuring window
                                positioning accepts the following keys:
 
@@ -670,6 +668,12 @@ nvim_open_win({buffer}, {enter}, {width}, {height}, {options})
                         the window can still be entered using
                         |nvim_set_current_win()| API call.
 
+                        `height`: window height in character cells. Cannot be
+                        smaller than 1.
+
+                        `width`: window width in character cells. Cannot be
+                        smaller than 2.
+
                         `row`: row position. Screen cell height are used as unit.
                         Can be floating point.
 
@@ -1561,21 +1565,38 @@ nvim_win_is_valid({window})                              *nvim_win_is_valid()*
                 Return: ~
                     true if the window is valid, false otherwise
 
-                                                           *nvim_win_config()*
+nvim_win_set_config({window}, {options})               *nvim_win_set_config()*
-nvim_win_config({window}, {width}, {height}, {options})
                 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. Pass in -1 for 'witdh' and 'height' to keep
+                parameters. Pass in 0 for `width` and `height` to keep
-                exiting size.
+                existing size.
 
                 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.
 
+                Parameters: ~
+                    {window}   Window handle
+                    {options}  Dictionary of options
+
+nvim_win_get_config({window})                          *nvim_win_get_config()*
+                Return window configuration.
+
+                Return a dictionary containing the same options that can be
+                given to |nvim_open_win()|.
+
+                `relative` will be empty for normal windows.
+
+                Parameters: ~
+                    {window}  Window handle
+
+                Return: ~
+                    Window configuration
+
 nvim_win_close({window}, {force})                           *nvim_win_close()*
                 Close a window.
 

src/nvim/api/window.c

@@ -439,11 +439,15 @@ Boolean nvim_win_is_valid(Window window)
 /// types).
 ///
 /// See documentation at |nvim_open_win()|, for the meaning of parameters. Pass
-/// in 0 for 'witdh' and 'height' to keep exiting size.
+/// in 0 for `width` and `height` to keep existing size.
 ///
 /// 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.
+///
+/// @param      window  Window handle
+/// @param      options Dictionary of options
+/// @param[out] err     Error details, if any
 void nvim_win_set_config(Window window, Dictionary options, Error *err)
   FUNC_API_SINCE(6)
 {
@@ -476,6 +480,8 @@ void nvim_win_set_config(Window window, Dictionary options, Error *err)
 /// Return a dictionary containing the same options that can be given to
 /// |nvim_open_win()|.
 ///
+/// `relative` will be empty for normal windows.
+///
 /// @param window Window handle
 /// @param[out] err Error details, if any
 /// @return Window configuration