diff --git a/doc/pages/command-parsing.asciidoc b/doc/pages/command-parsing.asciidoc
index 8e2adfdf41..60851e7c11 100644
--- a/doc/pages/command-parsing.asciidoc
+++ b/doc/pages/command-parsing.asciidoc
@@ -9,6 +9,14 @@ prompt, are parsed according to the following rules:
 
 - Words (command names and parameters) are delimited by whitespaces.
 
+- <<expansions#, Expansions>> are parsed and replaced before the execution of
+  the commands.
+
+== Comments parsing
+
+Commands are commented out after `#` until end of line (not `;`).
+`#` takes effect _after_ the expansions are parsed.
+
 == Quoted Strings
 
 If a word starts with `'`, `"`, or `%X` with `X` a _non-nestable_ punctuation