api: Add warnings about the returned value to \*del_var functions

5 files changed, 16 insertions, 5 deletions

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index a01188f98c..55b535c78c 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -449,7 +449,10 @@ Object buffer_set_var(Buffer buffer, String name, Object value, Error *err)
 /// @param buffer The buffer handle
 /// @param name The variable name
 /// @param[out] err Details of an error that may have occurred
-/// @return The old value
+/// @return The old value or nil if there was no previous value.
+///
+///         @warning It may return nil if there was no previous value
+///                  or if previous value was `v:null`.
 Object buffer_del_var(Buffer buffer, String name, Error *err)
 {
   buf_T *buf = find_buffer_by_handle(buffer, err);
diff --git a/src/nvim/api/private/defs.h b/src/nvim/api/private/defs.h
index 6c8e324649..fbfa87d5ae 100644
--- a/src/nvim/api/private/defs.h
+++ b/src/nvim/api/private/defs.h
@@ -99,4 +99,3 @@ struct key_value_pair {
 
 
 #endif  // NVIM_API_PRIVATE_DEFS_H
-
diff --git a/src/nvim/api/tabpage.c b/src/nvim/api/tabpage.c
index 3148a4fab7..c8311b0aa0 100644
--- a/src/nvim/api/tabpage.c
+++ b/src/nvim/api/tabpage.c
@@ -80,7 +80,10 @@ Object tabpage_set_var(Tabpage tabpage, String name, Object value, Error *err)
 /// @param tabpage handle
 /// @param name The variable name
 /// @param[out] err Details of an error that may have occurred
-/// @return The tab page handle
+/// @return The old value or nil if there was no previous value.
+///
+///         @warning It may return nil if there was no previous value
+///                  or if previous value was `v:null`.
 Object tabpage_del_var(Tabpage tabpage, String name, Error *err)
 {
   tabpage_T *tab = find_tab_by_handle(tabpage, err);
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index dcae08d24c..10110b0f62 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -349,7 +349,10 @@ Object vim_set_var(String name, Object value, Error *err)
 ///
 /// @param name The variable name
 /// @param[out] err Details of an error that may have occurred
-/// @return the old value if any
+/// @return The old value or nil if there was no previous value.
+///
+///         @warning It may return nil if there was no previous value
+///                  or if previous value was `v:null`.
 Object vim_del_var(String name, Error *err)
 {
   return dict_set_value(&globvardict, name, NIL, true, err);
diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
index cca1e3bdd3..a52f53a3e6 100644
--- a/src/nvim/api/window.c
+++ b/src/nvim/api/window.c
@@ -223,7 +223,10 @@ Object window_set_var(Window window, String name, Object value, Error *err)
 /// @param window The window handle
 /// @param name The variable name
 /// @param[out] err Details of an error that may have occurred
-/// @return The old value
+/// @return The old value or nil if there was no previous value.
+///
+///         @warning It may return nil if there was no previous value
+///                  or if previous value was `v:null`.
 Object window_del_var(Window window, String name, Error *err)
 {
   win_T *win = find_window_by_handle(window, err);