vim-patch:770eb7d: runtime(doc): clarify expandcmd() and "~" behaviour

fixes: vim/vim#20793

770eb7db17

Co-authored-by: Hirohito Higashi <h.east.727@gmail.com>

runtime/doc/vimfn.txt

@@ -2269,6 +2269,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:

runtime/lua/vim/_meta/vimfn.gen.lua

@@ -1993,6 +1993,10 @@ function vim.fn.expand(string, nosuf, list) end
 --- 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:

src/nvim/eval.lua

@@ -2518,6 +2518,10 @@ M.funcs = {
       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: