Merge pull request #23670 from famiu/refactor/deprecate_opt_api

refactor(options): deprecate nvim[_buf|_win]_[gs]et_option

5 files changed, 19 insertions, 59 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 1f65c3ac01..e7cda59906 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -486,7 +486,7 @@ Example: create a float with scratch buffer: >vim
         \ 'row': 1, 'anchor': 'NW', 'style': 'minimal'}
     let win = nvim_open_win(buf, 0, opts)
     " optional: change highlight, otherwise Pmenu is used
-    call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight')
+    call nvim_set_option_value('winhl', 'Normal:MyHighlight', {'win': win})
 <
 
 ==============================================================================
@@ -1917,25 +1917,6 @@ nvim_parse_cmd({str}, {opts})                               *nvim_parse_cmd()*
 ==============================================================================
 Options Functions                                                *api-options*
 
-nvim_buf_get_option({buffer}, {name})                  *nvim_buf_get_option()*
-    Gets a buffer option value
-
-    Parameters: ~
-      • {buffer}  Buffer handle, or 0 for current buffer
-      • {name}    Option name
-
-    Return: ~
-        Option value
-
-nvim_buf_set_option({buffer}, {name}, {value})         *nvim_buf_set_option()*
-    Sets a buffer option value. Passing `nil` as value deletes the option
-    (only works if there's a global fallback)
-
-    Parameters: ~
-      • {buffer}  Buffer handle, or 0 for current buffer
-      • {name}    Option name
-      • {value}   Option value
-
 nvim_get_all_options_info()                      *nvim_get_all_options_info()*
     Gets the option information for all options.
 
@@ -1945,15 +1926,6 @@ nvim_get_all_options_info()                      *nvim_get_all_options_info()*
     Return: ~
         dictionary of all options
 
-nvim_get_option({name})                                    *nvim_get_option()*
-    Gets the global value of an option.
-
-    Parameters: ~
-      • {name}  Option name
-
-    Return: ~
-        Option value (global)
-
 nvim_get_option_info2({name}, {*opts})               *nvim_get_option_info2()*
     Gets the option information for one option from arbitrary buffer or window
 
@@ -2010,13 +1982,6 @@ nvim_get_option_value({name}, {*opts})               *nvim_get_option_value()*
     Return: ~
         Option value
 
-nvim_set_option({name}, {value})                           *nvim_set_option()*
-    Sets the global value of an option.
-
-    Parameters: ~
-      • {name}   Option name
-      • {value}  New option value
-
                                                      *nvim_set_option_value()*
 nvim_set_option_value({name}, {value}, {*opts})
     Sets the value of an option. The behavior of this function matches that of
@@ -2034,25 +1999,6 @@ nvim_set_option_value({name}, {value}, {*opts})
                  • win: |window-ID|. Used for setting window local option.
                  • buf: Buffer number. Used for setting buffer local option.
 
-nvim_win_get_option({window}, {name})                  *nvim_win_get_option()*
-    Gets a window option value
-
-    Parameters: ~
-      • {window}  Window handle, or 0 for current window
-      • {name}    Option name
-
-    Return: ~
-        Option value
-
-nvim_win_set_option({window}, {name}, {value})         *nvim_win_set_option()*
-    Sets a window option value. Passing `nil` as value deletes the option
-    (only works if there's a global fallback)
-
-    Parameters: ~
-      • {window}  Window handle, or 0 for current window
-      • {name}    Option name
-      • {value}   Option value
-
 
 ==============================================================================
 Buffer Functions                                                  *api-buffer*
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 3150190a8b..9d4a7324bf 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -21,6 +21,12 @@ API
 - *nvim_get_hl_by_id()*		Use |nvim_get_hl()| instead.
 - *nvim_exec()*			Use |nvim_exec2()| instead.
 - *nvim_get_option_info()*	Use |nvim_get_option_info2()| instead.
+- *nvim_buf_get_option()*	Use |nvim_get_option_value()| instead.
+- *nvim_buf_set_option()*	Use |nvim_set_option_value()| instead.
+- *nvim_get_option()*		Use |nvim_get_option_value()| instead.
+- *nvim_set_option()*		Use |nvim_set_option_value()| instead.
+- *nvim_win_get_option()*	Use |nvim_get_option_value()| instead.
+- *nvim_win_set_option()*	Use |nvim_set_option_value()| instead.
 
 COMMANDS
 - *:rv* *:rviminfo*		Deprecated alias to |:rshada| command.
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index ca1a9a414d..98a0801013 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -800,8 +800,8 @@ formatexpr({opts})                                      *vim.lsp.formatexpr()*
 
     Currently only supports a single client. This can be set via `setlocal
     formatexpr=v:lua.vim.lsp.formatexpr()` but will typically or in
-    `on_attach` via `vim.api.nvim_buf_set_option(bufnr, 'formatexpr',
-    'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})')`.
+    `on_attach` via `vim.bo[bufnr].formatexpr =
+    'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`.
 
     Parameters: ~
       • {opts}  (table) options for customizing the formatting expression
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index c6568b073d..ad9cb69ae0 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -401,7 +401,7 @@ For example consider the following Lua omnifunc handler: >lua
         return {'stuff', 'steam', 'strange things'}
       end
     end
-    vim.api.nvim_buf_set_option(0, 'omnifunc', 'v:lua.mymod.omnifunc')
+    vim.bo[buf].omnifunc = 'v:lua.mymod.omnifunc'
 
 Note: The module ("mymod" in the above example) must either be a Lua global,
 or use require() as shown above to access it from a package.
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 11ef26165f..9f6ab2ddd0 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -84,7 +84,7 @@ The following deprecated functions or APIs were removed.
 ==============================================================================
 DEPRECATIONS                                                *news-deprecations*
 
-The following functions are now deprecated and will be removed in the next
+The following functions are now deprecated and will be removed in a future
 release.
 
 • Checkhealth functions:
@@ -94,4 +94,12 @@ release.
   - |health#report_start|, |vim.health.report_start()|	Use |vim.health.start()| instead.
   - |health#report_warn|, |vim.health.report_warn()|	Use |vim.health.warn()| instead.
 
+• |API| functions:
+  - |nvim_buf_get_option()|	Use |nvim_get_option_value()| instead.
+  - |nvim_buf_set_option()|	Use |nvim_set_option_value()| instead.
+  - |nvim_get_option()|		Use |nvim_get_option_value()| instead.
+  - |nvim_set_option()|		Use |nvim_set_option_value()| instead.
+  - |nvim_win_get_option()|	Use |nvim_get_option_value()| instead.
+  - |nvim_win_set_option()|	Use |nvim_set_option_value()| instead.
+
  vim:tw=78:ts=8:sw=2:et:ft=help:norl: