runtime(doc): clarify vim.eval behavior with Vim special variables

Problem:  The behavior of vim.eval() with Vim special variables is not
          clearly documented. It is (partly) the reason why Nvim
          Python's vim.eval gives different output when evaluating
          v:true and v:false
Solution: Document it (Phạm Bình An)

closes: #19157

Signed-off-by: Phạm Bình An <phambinhanctb2004@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt
index 65d1c8bedfb39cdad1a5648b43b8dc0b4bc03830..e50fe2e7ec5ab60122a97efce9095e36205105ca 100644 (file)
--- a/runtime/doc/if_pyth.txt
+++ b/runtime/doc/if_pyth.txt
@@ -1,4 +1,4 @@
-*if_pyth.txt*  For Vim version 9.1.  Last change: 2025 Nov 09
+*if_pyth.txt*  For Vim version 9.1.  Last change: 2026 Jan 11
 
 
                  VIM REFERENCE MANUAL    by Paul Moore
@@ -183,9 +183,11 @@ vim.eval(str)                                              *python-eval*
        Evaluates the expression str using the vim internal expression
        evaluator (see |expression|).  Returns the expression result as:
        - a string if the Vim expression evaluates to a string or number
-       - a list if the Vim expression evaluates to a Vim list
-       - a tuple if the Vim expression evaluates to a Vim tuple
-       - a dictionary if the Vim expression evaluates to a Vim dictionary
+       - a list if the Vim expression evaluates to a Vim |list|
+       - a tuple if the Vim expression evaluates to a Vim |tuple|
+       - a dictionary if the Vim expression evaluates to a Vim |dict|
+       - a boolean if Vim exression evaluates to |v:true| or |v:false|
+       - `None` if Vim expression evaluates to |v:null| or |v:none|
        Dictionaries, lists and tuples are recursively expanded.
        Examples: >
            :" value of the 'textwidth' option