Docs: Clean up of 'template' module docs (#46297)

* Docs: Clean up of 'template' module docs

* Changed influenced by review comments

1 files changed, 43 insertions, 49 deletions

diff --git a/lib/ansible/utils/module_docs_fragments/files.py b/lib/ansible/utils/module_docs_fragments/files.py
index b18c86b9a6..372325d2dd 100644
--- a/lib/ansible/utils/module_docs_fragments/files.py
+++ b/lib/ansible/utils/module_docs_fragments/files.py
@@ -1,19 +1,5 @@
-# (c) 2014, Matt Martz <matt@sivel.net>
-#
-# This file is part of Ansible
-#
-# Ansible is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation, either version 3 of the License, or
-# (at your option) any later version.
-#
-# Ansible is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with Ansible.  If not, see <http://www.gnu.org/licenses/>.
+# Copyright: (c) 2014, Matt Martz <matt@sivel.net>
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 
 class ModuleDocFragment(object):
@@ -22,56 +8,64 @@ class ModuleDocFragment(object):
 
     # Note: mode is overridden by the copy and template modules so if you change the description
     # here, you should also change it there.
-    DOCUMENTATION = """
+    DOCUMENTATION = r'''
 options:
   mode:
     description:
-      - "Mode the file or directory should be. 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 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 number which will have unexpected results.
-        As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r))."
+    - The permissions the resulting file or directory 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
+      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
+      number which will have unexpected results.
+    - As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or
+      C(u=rw,g=r,o=r)).
+    - As of version 2.6, the mode may also be the special string C(preserve).
+    - When set to C(preserve) the file will be given the same permissions as the source file.
   owner:
     description:
-      - Name of the user that should own the file/directory, as would be fed to I(chown).
+    - Name of the user that should own the file/directory, as would be fed to I(chown).
   group:
     description:
-      - Name of the group that should own the file/directory, as would be fed to I(chown).
+    - Name of the group that should own the file/directory, as would be fed to I(chown).
   seuser:
     description:
-      - User part of SELinux file context. Will default to system policy, if
-        applicable. If set to C(_default), it will use the C(user) portion of the
-        policy if available.
+    - The user part of the SELinux file context.
+    - By default it uses the C(system) policy, where applicable.
+    - When set to C(_default), it will use the C(user) portion of the policy if available.
   serole:
     description:
-      - Role part of SELinux file context, C(_default) feature works as for I(seuser).
+    - The role part of the SELinux file context.
+    - When set to C(_default), it will use the C(role) portion of the policy if available.
   setype:
     description:
-      - Type part of SELinux file context, C(_default) feature works as for I(seuser).
+    - The type part of the SELinux file context.
+    - When set to C(_default), it will use the C(type) portion of the policy if available.
   selevel:
     description:
-      - Level part of the SELinux file context. This is the MLS/MCS attribute,
-        sometimes known as the C(range). C(_default) feature works as for
-        I(seuser).
-    default: "s0"
+    - The level part of the SELinux file context.
+    - This is the MLS/MCS attribute, sometimes known as the C(range).
+    - When set to C(_default), it will use the C(level) portion of the policy if available.
+    default: s0
   unsafe_writes:
     description:
-      - By default this module uses atomic operations to prevent data
-        corruption or inconsistent reads from the target files,
-        but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted files,
-        which cannot be updated atomically from inside the container and can only be written in an unsafe manner.
-      - This option allows Ansible to fall back to unsafe methods of
-        updating files when atomic operations fail (however, it doesn't force Ansible to perform unsafe writes).
-        IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption.
+    - Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target file.
+    - By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target files,
+      but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted files,
+      which cannot be updated atomically from inside the container and can only be written in an unsafe manner.
+    - This option allows Ansible to fall back to unsafe methods of updating files when atomic operations fail
+      (however, it doesn't force Ansible to perform unsafe writes).
+    - IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption.
     type: bool
-    default: 'no'
-    version_added: "2.2"
+    default: no
+    version_added: '2.2'
   attributes:
     description:
-      - Attributes the file or directory should have. To get supported flags look at the man page for I(chattr) on the target system.
-        This string should contain the attributes in the same order as the one displayed by I(lsattr).
-      - C(=) operator is assumed as default, otherwise C(+) or C(-) operators need to be included in the string.
-    aliases: ['attr']
-    version_added: "2.3"
-"""
+    - The attributes the resulting file or directory should have.
+    - To get supported flags look at the man page for I(chattr) on the target system.
+    - This string should contain the attributes in the same order as the one displayed by I(lsattr).
+    - The C(=) operator is assumed as default, otherwise C(+) or C(-) operators need to be included in the string.
+    aliases: [ attr ]
+    version_added: '2.3'
+'''