From 3df1211ebc4c7ec4562d0ad0fa51a24569b81e15 Mon Sep 17 00:00:00 2001
From: Luna Saphie Mittelbach <lunarlambda@gmail.com>
Date: Mon, 4 Mar 2024 00:33:09 +0100
Subject: [PATCH] docs(lua): clarify when `vim.bo`/`vim.wo` acts like
 `:setlocal` (#27708)

---
 runtime/doc/lua.txt          | 16 +++++++++-------
 runtime/lua/vim/_options.lua | 12 ++++++------
 2 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index b4d66f11ae..c785106ca8 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1409,11 +1409,12 @@ Option:remove({value})                                      *vim.opt:remove()*
       • {value}  (`string`) Value to remove
 
 vim.bo                                                                *vim.bo*
-    Get or set buffer-scoped |options| for the buffer with number {bufnr}.
-    Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
-    buffer is used. Invalid {bufnr} or key is an error.
+    Get or set buffer-scoped |options| for the buffer with number {bufnr}. If
+    [{bufnr}] is omitted then the current buffer is used. Invalid {bufnr} or
+    key is an error.
 
-    Note: this is equivalent to both `:set` and `:setlocal`.
+    Note: this is equivalent to `:setlocal` for |global-local| options and
+    `:set` otherwise.
 
     Example: >lua
         local bufnr = vim.api.nvim_get_current_buf()
@@ -1462,9 +1463,10 @@ vim.o                                                                  *vim.o*
 
 vim.wo                                                                *vim.wo*
     Get or set window-scoped |options| for the window with handle {winid} and
-    buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
-    `:set` otherwise. If [{winid}] is omitted then the current window is used.
-    Invalid {winid}, {bufnr} or key is an error.
+    buffer with number {bufnr}. Like `:setlocal` if setting a |global-local|
+    option or if {bufnr} is provided, like `:set` otherwise. If [{winid}] is
+    omitted then the current window is used. Invalid {winid}, {bufnr} or key
+    is an error.
 
     Note: only {bufnr} with value `0` (the current buffer in the window) is
     supported.
diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index bde9421552..b661ddfb22 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -271,10 +271,10 @@ vim.go = setmetatable({}, {
 })
 
 --- Get or set buffer-scoped |options| for the buffer with number {bufnr}.
---- Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
---- buffer is used. Invalid {bufnr} or key is an error.
+--- If [{bufnr}] is omitted then the current buffer is used.
+--- Invalid {bufnr} or key is an error.
 ---
---- Note: this is equivalent to both `:set` and `:setlocal`.
+--- Note: this is equivalent to `:setlocal` for |global-local| options and `:set` otherwise.
 ---
 --- Example:
 ---
@@ -287,9 +287,9 @@ vim.go = setmetatable({}, {
 vim.bo = new_buf_opt_accessor()
 
 --- Get or set window-scoped |options| for the window with handle {winid} and
---- buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
---- `:set` otherwise. If [{winid}] is omitted then the current window is
---- used. Invalid {winid}, {bufnr} or key is an error.
+--- buffer with number {bufnr}. Like `:setlocal` if setting a |global-local| option
+--- or if {bufnr} is provided, like `:set` otherwise. If [{winid}] is omitted then
+--- the current window is used. Invalid {winid}, {bufnr} or key is an error.
 ---
 --- Note: only {bufnr} with value `0` (the current buffer in the window) is
 --- supported.