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.
     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
   checksum. This effectively doubles the transfer size, and
   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
   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