command module, fix docs to reflect reality (#84191)

though the previous docs were the 'intended' outcome,
the current behaviour has been active for a long time and should
not be removed due to backward compatibility issues.

One thing we can do going forward is deprecate substitution enabled by default.

(cherry picked from commit bf48b538f8)

lib/ansible/modules/command.py

@@ -16,12 +16,11 @@ version_added: historical
 description:
      - The M(ansible.builtin.command) module takes the command name followed by a list of space-delimited arguments.
      - The given command will be executed on all selected nodes.
-     - The command(s) will not be
+     - The command(s) will not be processed through the shell, so operations like C("*"), C("<"), C(">"), C("|"), C(";") and C("&") will not work.
-       processed through the shell, so variables like C($HOSTNAME) and operations
+       Also, environment variables are resolved via Python, not shell, see O(expand_argument_vars) and are left unchanged if not matched.
-       like C("*"), C("<"), C(">"), C("|"), C(";") and C("&") will not work.
        Use the M(ansible.builtin.shell) module if you need these features.
-     - To create C(command) tasks that are easier to read than the ones using space-delimited
+     - To create C(command) tasks that are easier to read than the ones using space-delimited arguments,
-       arguments, pass parameters using the C(args) L(task keyword,https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html#task)
+       pass parameters using the C(args) L(task keyword,https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html#task)
        or use O(cmd) parameter.
      - Either a free form command or O(cmd) parameter is required, see the examples.
      - For Windows targets, use the M(ansible.windows.win_command) module instead.
@@ -42,8 +41,8 @@ attributes:
 options:
   expand_argument_vars:
     description:
-      - Expands the arguments that are variables, for example C($HOME) will be expanded before being passed to the
+      - Expands the arguments that are variables, for example C($HOME) will be expanded before being passed to the command to run.
-        command to run.
+      - If a variable is not matched, it is left unchanged, unlike shell substitution which would remove it.
       - Set to V(false) to disable expansion and treat the value as a literal argument.
     type: bool
     default: true