runtime(doc): clarify expandcmd() and "~" behaviour

fixes: #20793

Signed-off-by: Hirohito Higashi <h.east.727@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index dc668c3a91922e22a0b66c52ad29d3c5e462b9ea..1f14e7528195229b675ea08b40ad2dbd49fc8a01 100644 (file)
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -3099,6 +3099,10 @@ expandcmd({string} [, {options}])                        *expandcmd()*
                like with |expand()|, and environment variables, anywhere in
                {string}.  "~user" and "~/path" are only expanded at the
                start.
+               The expansion is done in two steps: the special keywords are
+               evaluated first, then "~" and environment variables are
+               expanded in the result.  Thus `expand('%:~')` keeps the "~",
+               while `expandcmd('%:~')` returns the full path.
 
                The following items are supported in the {options} Dict
                argument: