diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt
index 7eccc6011d..cc5e21c08c 100644
--- a/runtime/doc/vimfn.txt
+++ b/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:
diff --git a/runtime/lua/vim/_meta/vimfn.gen.lua b/runtime/lua/vim/_meta/vimfn.gen.lua
index 3d9b12bbda..5bc52d2219 100644
--- a/runtime/lua/vim/_meta/vimfn.gen.lua
+++ b/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:
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
index 7323fef2a6..f95dc53190 100644
--- a/src/nvim/eval.lua
+++ b/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: