Merge pull request #27330 from seandewar/win_set_config-fixes

fix(api): various window-related function fixes

This is a big one!

5 files changed, 36 insertions, 38 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 87269ad147..0512814887 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3271,9 +3271,9 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                   • footer_pos: Footer position. Must be set with `footer`
                     option. Value can be one of "left", "center", or "right".
                     Default is `"left"`.
-                  • noautocmd: If true then no buffer-related autocommand
-                    events such as |BufEnter|, |BufLeave| or |BufWinEnter| may
-                    fire from calling this function.
+                  • noautocmd: If true then autocommands triggered from
+                    setting the `buffer` to display are blocked (e.g:
+                    |BufEnter|, |BufLeave|, |BufWinEnter|).
                   • fixed: If true when anchor is NW or SW, the float window
                     would be kept fixed even if the window would be truncated.
                   • hide: If true the floating window will be hidden.
@@ -3297,11 +3297,11 @@ nvim_win_get_config({window})                          *nvim_win_get_config()*
         Map defining the window configuration, see |nvim_open_win()|
 
 nvim_win_set_config({window}, {config})                *nvim_win_set_config()*
-    Configures window layout. Currently only for floating and external windows
-    (including changing a split window to those layouts).
+    Configures window layout. Cannot be used to move the last window in a
+    tabpage to a different one.
 
-    When reconfiguring a floating window, absent option keys will not be
-    changed. `row`/`col` and `relative` must be reconfigured together.
+    When reconfiguring a window, absent option keys will not be changed.
+    `row`/`col` and `relative` must be reconfigured together.
 
     Parameters: ~
       • {window}  Window handle, or 0 for current window
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index c5f3946871..4b1ccc0c5c 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -8901,10 +8901,10 @@ win_screenpos({nr})                                            *win_screenpos()*
 		tabpage.
 
 win_splitmove({nr}, {target} [, {options}])                    *win_splitmove()*
-		Move the window {nr} to a new split of the window {target}.
-		This is similar to moving to {target}, creating a new window
-		using |:split| but having the same contents as window {nr}, and
-		then closing {nr}.
+		Temporarily switch to window {target}, then move window {nr}
+		to a new split adjacent to {target}.
+		Unlike commands such as |:split|, no new windows are created
+		(the |window-ID| of window {nr} is unchanged after the move).
 
 		Both {nr} and {target} can be window numbers or |window-ID|s.
 		Both must be in the current tab page.
diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt
index b71e7c80ab..4791e73929 100644
--- a/runtime/doc/windows.txt
+++ b/runtime/doc/windows.txt
@@ -502,35 +502,33 @@ horizontally split windows.  CTRL-W H does it the other way around.
 
 						*CTRL-W_K*
 CTRL-W K	Move the current window to be at the very top, using the full
-		width of the screen.  This works like closing the current
-		window and then creating another one with ":topleft split",
-		except that the current window contents is used for the new
-		window.
+		width of the screen.  This works like `:topleft split`, except
+		it is applied to the current window and no new window is
+		created.
 
 						*CTRL-W_J*
 CTRL-W J	Move the current window to be at the very bottom, using the
-		full width of the screen.  This works like closing the current
-		window and then creating another one with ":botright split",
-		except that the current window contents is used for the new
-		window.
+		full width of the screen.  This works like `:botright split`,
+		except it is applied to the current window and no new window
+		is created.
 
 						*CTRL-W_H*
 CTRL-W H	Move the current window to be at the far left, using the
-		full height of the screen.  This works like closing the
-		current window and then creating another one with
-		`:vert topleft split`, except that the current window contents
-		is used for the new window.
+		full height of the screen.  This works like
+		`:vert topleft split`, except it is applied to the current
+		window and no new window is created.
 
 						*CTRL-W_L*
 CTRL-W L	Move the current window to be at the far right, using the full
-		height of the screen.  This works like closing the
-		current window and then creating another one with
-		`:vert botright split`, except that the current window
-		contents is used for the new window.
+		height of the screen.  This works like `:vert botright split`,
+		except it is applied to the current window and no new window
+		is created.
 
 						*CTRL-W_T*
 CTRL-W T	Move the current window to a new tab page.  This fails if
 		there is only one window in the current tab page.
+		This works like `:tab split`, except the previous window is
+		closed.
 		When a count is specified the new tab page will be opened
 		before the tab page with this index.  Otherwise it comes after
 		the current tab page.
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index cb4c8749b8..ed8128769d 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -1718,9 +1718,9 @@ function vim.api.nvim_open_term(buffer, opts) end
 ---               • footer_pos: Footer position. Must be set with `footer`
 ---                 option. Value can be one of "left", "center", or "right".
 ---                 Default is `"left"`.
----               • noautocmd: If true then no buffer-related autocommand
----                 events such as `BufEnter`, `BufLeave` or `BufWinEnter` may
----                 fire from calling this function.
+---               • noautocmd: If true then autocommands triggered from
+---                 setting the `buffer` to display are blocked (e.g:
+---                 `BufEnter`, `BufLeave`, `BufWinEnter`).
 ---               • fixed: If true when anchor is NW or SW, the float window
 ---                 would be kept fixed even if the window would be truncated.
 ---               • hide: If true the floating window will be hidden.
@@ -2223,11 +2223,11 @@ function vim.api.nvim_win_remove_ns(window, ns_id) end
 --- @param buffer integer Buffer handle
 function vim.api.nvim_win_set_buf(window, buffer) end
 
---- Configures window layout. Currently only for floating and external windows
---- (including changing a split window to those layouts).
+--- Configures window layout. Cannot be used to move the last window in a
+--- tabpage to a different one.
 ---
---- When reconfiguring a floating window, absent option keys will not be
---- changed. `row`/`col` and `relative` must be reconfigured together.
+--- When reconfiguring a window, absent option keys will not be changed.
+--- `row`/`col` and `relative` must be reconfigured together.
 ---
 --- @param window integer Window handle, or 0 for current window
 --- @param config vim.api.keyset.win_config Map defining the window configuration, see `nvim_open_win()`
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index ac25547212..ee68f669f8 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -10598,10 +10598,10 @@ function vim.fn.win_move_statusline(nr, offset) end
 --- @return any
 function vim.fn.win_screenpos(nr) end
 
---- Move the window {nr} to a new split of the window {target}.
---- This is similar to moving to {target}, creating a new window
---- using |:split| but having the same contents as window {nr}, and
---- then closing {nr}.
+--- Temporarily switch to window {target}, then move window {nr}
+--- to a new split adjacent to {target}.
+--- Unlike commands such as |:split|, no new windows are created
+--- (the |window-ID| of window {nr} is unchanged after the move).
 ---
 --- Both {nr} and {target} can be window numbers or |window-ID|s.
 --- Both must be in the current tab page.