From 2478a7fbbdcf2fe971e5a606b0a6b0ba45dee0f7 Mon Sep 17 00:00:00 2001
From: Sean Dewar <6256228+seandewar@users.noreply.github.com>
Date: Mon, 23 Feb 2026 15:10:20 +0000
Subject: [PATCH] docs(api): nvim_open_win "split" with negative "win" #38032

Acts like :topleft/botright.
---
 runtime/doc/api.txt           | 3 ++-
 runtime/lua/vim/_meta/api.lua | 4 ++--
 src/nvim/api/win_config.c     | 4 ++--
 3 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index e989ef4f61..73f53bd592 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -3923,7 +3923,8 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                   • vertical: Split vertically |:vertical|.
                   • width: Window width (in character cells). Minimum of 1.
                   • win: |window-ID| window to split, or relative window when
-                    creating a float (relative="win").
+                    creating a float (relative="win"). When splitting,
+                    negative value works like |:topleft|, |:botright|.
                   • zindex: Stacking order. floats with higher `zindex` go on
                     top on floats with lower indices. Must be larger than
                     zero. The following screen elements have hard-coded
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 47a7fa3ffd..6bc5328fd0 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -1847,8 +1847,8 @@ function vim.api.nvim_open_term(buffer, opts) end
 ---     Default is `"left"`.
 --- - vertical: Split vertically `:vertical`.
 --- - width: Window width (in character cells). Minimum of 1.
---- - win: `window-ID` window to split, or relative window when creating a
----    float (relative="win").
+--- - win: `window-ID` window to split, or relative window when creating a float (relative="win").
+---     When splitting, negative value works like `:topleft`, `:botright`.
 --- - zindex: Stacking order. floats with higher `zindex` go on top on
 ---             floats with lower indices. Must be larger than zero. The
 ---             following screen elements have hard-coded z-indices:
diff --git a/src/nvim/api/win_config.c b/src/nvim/api/win_config.c
index 55084c9cea..4bfa3b6284 100644
--- a/src/nvim/api/win_config.c
+++ b/src/nvim/api/win_config.c
@@ -183,8 +183,8 @@
 ///       Default is `"left"`.
 ///   - vertical: Split vertically |:vertical|.
 ///   - width: Window width (in character cells). Minimum of 1.
-///   - win: |window-ID| window to split, or relative window when creating a
-///      float (relative="win").
+///   - win: |window-ID| window to split, or relative window when creating a float (relative="win").
+///       When splitting, negative value works like |:topleft|, |:botright|.
 ///   - zindex: Stacking order. floats with higher `zindex` go on top on
 ///               floats with lower indices. Must be larger than zero. The
 ///               following screen elements have hard-coded z-indices: