documents approaches to octal modes better (#80112)

lib/ansible/plugins/doc_fragments/files.py

@@ -18,10 +18,11 @@ options:
     description:
     - The permissions the resulting filesystem object should have.
     - For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers.
-      You must either add a leading zero so that Ansible's YAML parser knows it is an octal number
-      (like C(0644) or C(01777)) or quote it (like C('644') or C('1777')) so Ansible receives
+      You must give Ansible enough information to parse them correctly.
+      For consistent results, quote octal numbers (for example, C('644') or C('1777')) so Ansible receives
       a string and can do its own conversion from string into number.
-    - Giving Ansible a number without following one of these rules will end up with a decimal
+      Adding a leading zero (for example, C(0755)) works sometimes, but can fail in loops and some other circumstances.
+    - Giving Ansible a number without following either of these rules will end up with a decimal
       number which will have unexpected results.
     - As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or
       C(u=rw,g=r,o=r)).