api/documentation: Add a warning that nil may mean v:null

1 files changed, 4 insertions, 1 deletions

diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
index 58218af09d..cca1e3bdd3 100644
--- a/src/nvim/api/window.c
+++ b/src/nvim/api/window.c
@@ -203,7 +203,10 @@ Object window_get_var(Window window, String name, Error *err)
 /// @param name The variable name
 /// @param value The variable value
 /// @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_set_var(Window window, String name, Object value, Error *err)
 {
   win_T *win = find_window_by_handle(window, err);