Docs: Clean up of 'fetch' module docs (#46330)

* Docs: Clean up of 'fetch' module docs

This is part of a series of module doc cleanups.

* Fixes as suggested by review

lib/ansible/modules/files/fetch.py

@@ -1,101 +1,101 @@
-# this is a virtual module that is entirely implemented server side
+#!/usr/bin/python
+# -*- coding: utf-8 -*-
+
 # Copyright: (c) 2017, Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
+# This is a virtual module that is entirely implemented as an action plugin and runs on the controller
+
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = '''
 ---
 module: fetch
-short_description: Fetches a file from remote nodes
+short_description: Fetch files from remote nodes
 description:
-     - This module works like M(copy), but in reverse. It is used for fetching
+- This module works like M(copy), but in reverse.
-       files from remote machines and storing them locally in a file tree,
+- It is used for fetching files from remote machines and storing them locally in a file tree, organized by hostname.
-       organized by hostname.
+- This module is also supported for Windows targets.
-     - This module is also supported for Windows targets.
+version_added: '0.2'
-version_added: "0.2"
 options:
   src:
     description:
-      - The file on the remote system to fetch. This I(must) be a file, not a
+    - The file on the remote system to fetch.
-        directory. Recursive fetching may be supported in a later release.
+    - This I(must) be a file, not a directory.
-    required: true
+    - Recursive fetching may be supported in a later release.
+    required: yes
   dest:
     description:
-      - A directory to save the file into. For example, if the I(dest)
+    - A directory to save the file into.
-        directory is C(/backup) a I(src) file named C(/etc/profile) on host
+    - For example, if the I(dest) directory is C(/backup) a I(src) file named C(/etc/profile) on host
-        C(host.example.com), would be saved into
+      C(host.example.com), would be saved into C(/backup/host.example.com/etc/profile).
-        C(/backup/host.example.com/etc/profile)
+    required: yes
-    required: true
   fail_on_missing:
-    version_added: "1.1"
+    version_added: '1.1'
     description:
-      - When set to 'yes', the task will fail if the remote file cannot be
+    - When set to C(yes), the task will fail if the remote file cannot be read for any reason.
-        read for any reason.  Prior to Ansible-2.5, setting this would only fail
+    - Prior to Ansible 2.5, setting this would only fail if the source file was missing.
-        if the source file was missing.
+    - The default was changed to C(yes) in Ansible 2.5.
-      - The default was changed to "yes" in Ansible-2.5.
     type: bool
-    default: 'yes'
+    default: yes
   validate_checksum:
-    version_added: "1.4"
+    version_added: '1.4'
     description:
-      - Verify that the source and destination checksums match after the files are fetched.
+    - Verify that the source and destination checksums match after the files are fetched.
     type: bool
-    default: 'yes'
+    default: yes
   flat:
-    version_added: "1.2"
+    version_added: '1.2'
     description:
-      - Allows you to override the default behavior of appending
+    - Allows you to override the default behavior of appending hostname/path/to/file to the destination.
-        hostname/path/to/file to the destination.  If dest ends with '/', it
+    - If C(dest) ends with '/', it will use the basename of the source file, similar to the copy module.
-        will use the basename of the source file, similar to the copy module.
+    - Obviously this is only handy if the filenames are unique.
-        Obviously this is only handy if the filenames are unique.
     type: bool
-    default: 'no'
+    default: no
 author:
-    - "Ansible Core Team"
+- Ansible Core Team
-    - "Michael DeHaan"
+- Michael DeHaan
 notes:
-    - When running fetch with C(become), the M(slurp) module will also be
+- When running fetch with C(become), the M(slurp) module will also be
-      used to fetch the contents of the file for determining the remote
+  used to fetch the contents of the file for determining the remote
-      checksum. This effectively doubles the transfer size, and
+  checksum. This effectively doubles the transfer size, and
-      depending on the file size can consume all available memory on the
+  depending on the file size can consume all available memory on the
-      remote or local hosts causing a C(MemoryError). Due to this it is
+  remote or local hosts causing a C(MemoryError). Due to this it is
-      advisable to run this module without C(become) whenever possible.
+  advisable to run this module without C(become) whenever possible.
-    - Prior to Ansible-2.5 this module would not fail if reading the remote
+- Prior to Ansible 2.5 this module would not fail if reading the remote
-      file was impossible unless fail_on_missing was set.  In Ansible-2.5+,
+  file was impossible unless C(fail_on_missing) was set.
-      playbook authors are encouraged to use fail_when or ignore_errors to
+- In Ansible 2.5 or later, playbook authors are encouraged to use
-      get this ability.  They may also explicitly set fail_on_missing to False
+  C(fail_when) or C(ignore_errors) to get this ability. They may
-      to get the non-failing behaviour.
+  also explicitly set C(fail_on_missing) to C(no) to get the
-    - This module is also supported for Windows targets.
+  non-failing behaviour.
+- This module is also supported for Windows targets.
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
-# Store file into /tmp/fetched/host.example.com/tmp/somefile
+- name: Store file into /tmp/fetched/host.example.com/tmp/somefile
-- fetch:
+  fetch:
     src: /tmp/somefile
     dest: /tmp/fetched
 
-# Specifying a path directly
+- name: Specifying a path directly
-- fetch:
+  fetch:
     src: /tmp/somefile
     dest: /tmp/prefix-{{ inventory_hostname }}
     flat: yes
 
-# Specifying a destination path
+- name: Specifying a destination path
-- fetch:
+  fetch:
     src: /tmp/uniquefile
     dest: /tmp/special/
     flat: yes
 
-# Storing in a path relative to the playbook
+- name: Storing in a path relative to the playbook
-- fetch:
+  fetch:
     src: /tmp/uniquefile
     dest: special/prefix-{{ inventory_hostname }}
     flat: yes