Manual cherry pick of commit e4a2d2423acde4ff53cd692b672748cfc8dfa465 in PR 47912 due to deleted

repository. As requested back port documentation change from devel(2.8) to stable-2.7

lib/ansible/modules/files/lineinfile.py

@@ -42,11 +42,15 @@ options:
   regexp:
     aliases: [ 'regex' ]
     description:
-      - The regular expression to look for in every line of the file. For
+      - The regular expression to look for in every line of the file.
-        C(state=present), the pattern to replace if found. Only the last line
+      - For C(state=present), the pattern to replace if found. Only the last line found will be replaced.
-        found will be replaced. For C(state=absent), the pattern of the line(s)
+      - For C(state=absent), the pattern of the line(s) to remove.
-        to remove. Uses Python regular expressions.
+      - If the regular expression is not matched, the line will be
-        See U(http://docs.python.org/2/library/re.html).
+        added to the file in keeping with`insertbefore` or `insertafter`
+        settings.
+      - When modifying a line the regexp should typically match both the initial state of
+        the line as well as its state after replacement by C(line) to ensure idempotence.
+      - Uses Python regular expressions. See U(http://docs.python.org/2/library/re.html).
     version_added: '1.7'
   state:
     description: