diff --git a/lib/ansible/modules/files/replace.py b/lib/ansible/modules/files/replace.py
index 90ecbacb3ba..2c0f31f4850 100644
--- a/lib/ansible/modules/files/replace.py
+++ b/lib/ansible/modules/files/replace.py
@@ -40,12 +40,16 @@ options:
       - The regular expression to look for in the contents of the file.
         Uses Python regular expressions; see
         U(http://docs.python.org/2/library/re.html).
-        Uses multiline mode, which means C(^) and C($) match the beginning
-        and end respectively of I(each line) of the file.
+        Uses MULTILINE mode, which means C(^) and C($) match the beginning
+        and end of the file, as well as the beginning and end respectively
+        of I(each line) of the file.
+      - Does not use DOTALL, which means the C(.) special character matches
+        any character I(except newlines). A common mistake is to assume that
+        a negated character set like C([^#]) will also not match newlines.
+        In order to exclude newlines, they must be added to the set like C([^#\\n]).
       - Note that, as of ansible 2, short form tasks should have any escape
         sequences backslash-escaped in order to prevent them being parsed
         as string literal escapes. See the examples.
-
   replace:
     required: false
     description: