utilities: Clean up parameter types and add seealso (#53063)

* utilities: Clean up parameter types and add seealso

* Add inventory modules

* Add more references, clarify with-loops

docs/docsite/rst/user_guide/playbooks_reuse_includes.rst

@@ -1,6 +1,8 @@
 Including and Importing
 =======================
 
+.. _playbooks_reuse_includes:
+
 .. contents:: Topics
 
 Includes vs. Imports

lib/ansible/modules/inventory/add_host.py

@@ -1,81 +1,83 @@
 # -*- mode: python -*-
-#
+
+# Copyright: (c) 2012, Seth Vidal (@skvidal)
 # Copyright: Ansible Team
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: add_host
-short_description: add a host (and alternatively a group) to the ansible-playbook in-memory inventory
+short_description: Add a host (and alternatively a group) to the ansible-playbook in-memory inventory
 description:
-  - Use variables to create new hosts and groups in inventory for use in later plays of the same playbook.
+- Use variables to create new hosts and groups in inventory for use in later plays of the same playbook.
-    Takes variables so you can define the new hosts more fully.
+- Takes variables so you can define the new hosts more fully.
-  - This module is also supported for Windows targets.
+- This module is also supported for Windows targets.
 version_added: "0.9"
 options:
   name:
-    aliases: [ 'hostname', 'host' ]
     description:
     - The hostname/ip of the host to add to the inventory, can include a colon and a port number.
+    type: str
     required: true
+    aliases: [ host, hostname ]
   groups:
-    aliases: [ 'groupname', 'group' ]
     description:
-    - The groups to add the hostname to, comma separated.
+    - The groups to add the hostname to.
-    required: false
+    type: list
+    aliases: [ group, groupname ]
 notes:
-    - This module bypasses the play host loop and only runs once for all the hosts in the play, if you need it
+- This module bypasses the play host loop and only runs once for all the hosts in the play, if you need it
-      to iterate use a with\_ directive.
+  to iterate use a with-loop construct.
-    - Windows targets are supported by this module.
+- The alias C(host) of the parameter C(name) is only available on Ansible 2.4 and newer.
-    - The alias 'host' of the parameter 'name' is only available on >=2.4
+- Since Ansible 2.4, the C(inventory_dir) variable is now set to C(None) instead of the 'global inventory source',
-    - Since Ansible version 2.4, the ``inventory_dir`` variable is now set to ``None`` instead of the 'global inventory source',
+  because you can now have multiple sources.  An example was added that shows how to partially restore the previous behaviour.
-      because you can now have multiple sources.  An example was added that shows how to partially restore the previous behaviour.
+- Windows targets are supported by this module.
+seealso:
+- module: group_by
 author:
-    - "Ansible Core Team"
+- Ansible Core Team
-    - "Seth Vidal (@skvidal)"
+- Seth Vidal (@skvidal)
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
-- name: add host to group 'just_created' with variable foo=42
+- name: Add host to group 'just_created' with variable foo=42
   add_host:
-    name: "{{ ip_from_ec2 }}"
+    name: '{{ ip_from_ec2 }}'
     groups: just_created
     foo: 42
 
-- name: add host to multiple groups
+- name: Add host to multiple groups
   add_host:
-    hostname: "{{ new_ip }}"
+    hostname: '{{ new_ip }}'
     groups:
-      - group1
+    - group1
-      - group2
+    - group2
 
-- name: add a host with a non-standard port local to your machines
+- name: Add a host with a non-standard port local to your machines
   add_host:
-    name: "{{ new_ip }}:{{ new_port }}"
+    name: '{{ new_ip }}:{{ new_port }}'
 
-- name: add a host alias that we reach through a tunnel (Ansible <= 1.9)
+- name: Add a host alias that we reach through a tunnel (Ansible 1.9 and older)
   add_host:
-    hostname: "{{ new_ip }}"
+    hostname: '{{ new_ip }}'
-    ansible_ssh_host: "{{ inventory_hostname }}"
+    ansible_ssh_host: '{{ inventory_hostname }}'
-    ansible_ssh_port: "{{ new_port }}"
+    ansible_ssh_port: '{{ new_port }}'
 
-- name: add a host alias that we reach through a tunnel (Ansible >= 2.0)
+- name: Add a host alias that we reach through a tunnel (Ansible 2.0 and newer)
   add_host:
-    hostname: "{{ new_ip }}"
+    hostname: '{{ new_ip }}'
-    ansible_host: "{{ inventory_hostname }}"
+    ansible_host: '{{ inventory_hostname }}'
-    ansible_port: "{{ new_port }}"
+    ansible_port: '{{ new_port }}'
 
-- name: Ensure inventory vars are set to the same value as the inventory_hostname has (close to pre 2.4 behaviour)
+- name: Ensure inventory vars are set to the same value as the inventory_hostname has (close to pre Ansible 2.4 behaviour)
   add_host:
     hostname: charlie
-    inventory_dir: "{{inventory_dir}}"
+    inventory_dir: '{{ inventory_dir }}'
 '''

lib/ansible/modules/inventory/group_by.py

@@ -1,43 +1,46 @@
 # -*- mode: python -*-
-#
+
+# Copyright: (c) 2012, Jeroen Hoekx (@jhoekx)
 # Copyright: Ansible Team
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 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: group_by
 short_description: Create Ansible groups based on facts
 description:
-  - Use facts to create ad-hoc groups that can be used later in a playbook.
+- Use facts to create ad-hoc groups that can be used later in a playbook.
-  - This module is also supported for Windows targets.
+- This module is also supported for Windows targets.
 version_added: "0.9"
 options:
   key:
     description:
-    - The variables whose values will be used as groups
+    - The variables whose values will be used as groups.
+    type: str
     required: true
   parents:
     description:
-    - The list of the parent groups
+    - The list of the parent groups.
-    required: false
+    type: list
-    default: "all"
+    default: all
     version_added: "2.4"
-author: "Jeroen Hoekx (@jhoekx)"
 notes:
-  - Spaces in group names are converted to dashes '-'.
+- Spaces in group names are converted to dashes '-'.
-  - This module is also supported for Windows targets.
+- This module is also supported for Windows targets.
+seealso:
+- module: add_host
+author:
+- Jeroen Hoekx (@jhoekx)
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
 # Create groups based on the machine architecture
 - group_by:
     key: machine_{{ ansible_machine }}
@@ -51,5 +54,4 @@ EXAMPLES = '''
     key: el{{ ansible_distribution_major_version }}-{{ ansible_architecture }}
     parents:
       - el{{ ansible_distribution_major_version }}
-
 '''

lib/ansible/modules/utilities/helper/_accelerate.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2013, James Cammarata <jcammarata@ansible.com>
+# Copyright: (c) 2013, James Cammarata <jcammarata@ansible.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function

lib/ansible/modules/utilities/helper/meta.py

@@ -1,74 +1,82 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2016, Ansible, a Red Hat company
+# Copyright: (c) 2016, Ansible, a Red Hat company
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'core'}
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = '''
 module: meta
 short_description: Execute Ansible 'actions'
-version_added: "1.2"
+version_added: '1.2'
 description:
-    - Meta tasks are a special kind of task which can influence Ansible internal execution or state. Prior to Ansible 2.0,
+    - Meta tasks are a special kind of task which can influence Ansible internal execution or state.
-      the only meta option available was `flush_handlers`. As of 2.2, there are five meta tasks which can be used.
+    - Prior to Ansible 2.0, the only meta option available was C(flush_handlers).
-      Meta tasks can be used anywhere within your playbook.
+    - As of Ansible 2.2, there are five meta tasks which can be used.
+    - Meta tasks can be used anywhere within your playbook.
     - This module is also supported for Windows targets.
 options:
   free_form:
     description:
-        - This module takes a free form command, as a string. There's not an actual option named "free form".  See the examples!
+        - This module takes a free form command, as a string. There is not an actual option named "free form".  See the examples!
-        - >
+        - C(flush_handlers) makes Ansible run any handler tasks which have thus far been notified. Ansible inserts these tasks internally at certain
-          C(flush_handlers) makes Ansible run any handler tasks which have thus far been notified. Ansible inserts these tasks internally at certain
           points to implicitly trigger handler runs (after pre/post tasks, the final role execution, and the main tasks section of your plays).
-        - >
+        - C(refresh_inventory) (added in Ansible 2.0) forces the reload of the inventory, which in the case of dynamic inventory scripts means they will be
-          C(refresh_inventory) (added in 2.0) forces the reload of the inventory, which in the case of dynamic inventory scripts means they will be
           re-executed. If the dynamic inventory script is using a cache, Ansible cannot know this and has no way of refreshing it (you can disable the cache
-          or, if available for your specific inventory datasource (for es.: aws), you can use the an inventory plugin instead of an inventory script).
+          or, if available for your specific inventory datasource (e.g. aws), you can use the an inventory plugin instead of an inventory script).
-          This is mainly useful when additional hosts are created and users wish to use them instead of using the `add_host` module."
+          This is mainly useful when additional hosts are created and users wish to use them instead of using the M(add_host) module.
-        - "C(noop) (added in 2.0) This literally does 'nothing'. It is mainly used internally and not recommended for general use."
+        - C(noop) (added in Ansible 2.0) This literally does 'nothing'. It is mainly used internally and not recommended for general use.
-        - "C(clear_facts) (added in 2.1) causes the gathered facts for the hosts specified in the play's list of hosts to be cleared, including the fact cache."
+        - C(clear_facts) (added in Ansible 2.1) causes the gathered facts for the hosts specified in the play's list of hosts to be cleared,
-        - "C(clear_host_errors) (added in 2.1) clears the failed state (if any) from hosts specified in the play's list of hosts."
+          including the fact cache.
-        - "C(end_play) (added in 2.2) causes the play to end without failing the host(s). Note that this affects all hosts."
+        - C(clear_host_errors) (added in Ansible 2.1) clears the failed state (if any) from hosts specified in the play's list of hosts.
-        - "C(reset_connection) (added in 2.3) interrupts a persistent connection (i.e. ssh + control persist)"
+        - C(end_play) (added in Ansible 2.2) causes the play to end without failing the host(s). Note that this affects all hosts.
-        - "C(end_host) (added in 2.8) is a per-host variation of C(end_play). Causes the play to end for the current host without failing it."
+        - C(reset_connection) (added in Ansible 2.3) interrupts a persistent connection (i.e. ssh + control persist)
-    choices: ['flush_handlers', 'refresh_inventory', 'noop', 'clear_facts', 'clear_host_errors', 'end_play', 'reset_connection', 'end_host']
+        - C(end_host) (added in Ansible 2.8) is a per-host variation of C(end_play). Causes the play to end for the current host without failing it.
+    choices: [ clear_facts, clear_host_errors, end_host, end_play, flush_handlers, noop, refresh_inventory, reset_connection ]
     required: true
 notes:
     - C(meta) is not really a module nor action_plugin as such it cannot be overwritten.
+    - C(clear_facts) will remove the persistent facts from M(set_fact) using C(cacheable=True),
+      but not the current host variable it creates for the current run.
     - This module is also supported for Windows targets.
-    - "C(clear_facts) will remove the persistent facts from ``set_fact: cacheable=True``, but not the current host variable it creates for the current run."
+seealso:
+- module: assert
+- module: fail
 author:
-    - "Ansible Core Team"
+    - Ansible Core Team
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
+# Example showing flushing handlers on demand, not at end of play
 - template:
     src: new.j2
     dest: /etc/config.txt
   notify: myhandler
-- name: force all notified handlers to run at this point, not waiting for normal sync points
+
+- name: Force all notified handlers to run at this point, not waiting for normal sync points
   meta: flush_handlers
 
-- name: reload inventory, useful with dynamic inventories when play makes changes to the existing hosts
+# Example showing how to refresh inventory during play
+- name: Reload inventory, useful with dynamic inventories when play makes changes to the existing hosts
   cloud_guest:            # this is fake module
     name: newhost
     state: present
+
 - name: Refresh inventory to ensure new instances exist in inventory
   meta: refresh_inventory
 
+# Example showing how to clear all existing facts of targetted hosts
 - name: Clear gathered facts from all currently targeted hosts
   meta: clear_facts
 
-- name: bring host back to play after failure
+# Example showing how to continue using a failed target
+- name: Bring host back to play after failure
   copy:
     src: file
     dest: /etc/file
@@ -76,13 +84,18 @@ EXAMPLES = '''
 
 - meta: clear_host_errors
 
-- user: name={{ansible_user}} groups=input
+# Example showing how to reset an existing connection
-- name: reset ssh connection to allow user changes to affect 'current login user'
+- user:
+    name: '{{ ansible_user }}'
+    groups: input
+
+- name: Reset ssh connection to allow user changes to affect 'current login user'
   meta: reset_connection
 
+# Example showing how to end the play for specific targets
 - name: End the play for hosts that run CentOS 6
   meta: end_host
   when:
-    - ansible_distribution == 'CentOS'
+  - ansible_distribution == 'CentOS'
-    - ansible_distribution_major_version == '6'
+  - ansible_distribution_major_version == '6'
 '''

lib/ansible/modules/utilities/logic/assert.py

@@ -1,19 +1,17 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright 2012 Dag Wieers <dag@wieers.com>
+# Copyright: (c) 2012, Dag Wieers <dag@wieers.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 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: assert
 short_description: Asserts given expressions are true
@@ -24,60 +22,65 @@ version_added: "1.5"
 options:
   that:
     description:
-      - "A string expression of the same form that can be passed to the 'when' statement."
+      - A list of string expressions of the same form that can be passed to the 'when' statement.
-      - "Alternatively, a list of string expressions."
+    type: list
     required: true
   fail_msg:
-    version_added: "2.7"
     description:
-      - "The customized message used for a failing assertion."
+      - The customized message used for a failing assertion.
-      - "This argument was called 'msg' before version 2.7, now it's renamed to 'fail_msg' with alias 'msg'."
+      - This argument was called 'msg' before Ansible 2.7, now it is renamed to 'fail_msg' with alias 'msg'.
-    aliases:
+    type: str
-      - msg
+    aliases: [ msg ]
+    version_added: "2.7"
   success_msg:
+    description:
+      - The customized message used for a successful assertion.
+    type: str
     version_added: "2.7"
-    description:
-      - "The customized message used for a successful assertion."
   quiet:
-    version_added: "2.8"
     description:
-      - "Set this to C(true) to avoid verbose output."
+      - Set this to C(yes) to avoid verbose output.
     type: bool
-    default: false
+    default: no
+    version_added: "2.8"
 notes:
      - This module is also supported for Windows targets.
+seealso:
+- module: debug
+- module: fail
+- module: meta
 author:
-    - "Ansible Core Team"
+    - Ansible Core Team
-    - "Michael DeHaan"
+    - Michael DeHaan
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
 - assert: { that: "ansible_os_family != 'RedHat'" }
 
 - assert:
     that:
       - "'foo' in some_command_result.stdout"
-      - "number_of_the_counting == 3"
+      - number_of_the_counting == 3
 
-- name: after version 2.7 both 'msg' and 'fail_msg' can customize failing assertion message
+- name: After version 2.7 both 'msg' and 'fail_msg' can customize failing assertion message
   assert:
     that:
-      - "my_param <= 100"
+      - my_param <= 100
-      - "my_param >= 0"
+      - my_param >= 0
     fail_msg: "'my_param' must be between 0 and 100"
     success_msg: "'my_param' is between 0 and 100"
 
-- name: please use 'msg' when ansible version is smaller than 2.7
+- name: Please use 'msg' when ansible version is smaller than 2.7
   assert:
     that:
-      - "my_param <= 100"
+      - my_param <= 100
-      - "my_param >= 0"
+      - my_param >= 0
     msg: "'my_param' must be between 0 and 100"
 
 - name: use quiet to avoid verbose output
   assert:
     that:
-      - "my_param <= 100"
+      - my_param <= 100
-      - "my_param >= 0"
+      - my_param >= 0
     quiet: true
 '''

lib/ansible/modules/utilities/logic/async_status.py

@@ -1,59 +1,99 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
+# Copyright: (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 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: async_status
 short_description: Obtain status of asynchronous task
 description:
-     - This module gets the status of an asynchronous task.
+- This module gets the status of an asynchronous task.
-     - This module is also supported for Windows targets.
+- This module is also supported for Windows targets.
 version_added: "0.5"
 options:
   jid:
     description:
-      - Job or task identifier
+    - Job or task identifier
+    type: str
     required: true
   mode:
     description:
-      - if C(status), obtain the status; if C(cleanup), clean up the async job cache (by default in C(~/.ansible_async/)) for the specified job I(jid).
+    - If C(status), obtain the status.
-    choices: [ "status", "cleanup" ]
+    - If C(cleanup), clean up the async job cache (by default in C(~/.ansible_async/)) for the specified job I(jid).
-    default: "status"
+    type: str
+    choices: [ cleanup, status ]
+    default: status
 notes:
-    - See also U(https://docs.ansible.com/playbooks_async.html)
+- This module is also supported for Windows targets.
-    - This module is also supported for Windows targets.
+seealso:
+- module: async_wrapper
+- ref: playbooks_async
+  description: Detailed information on how to use asynchronous actions and polling.
 author:
-    - "Ansible Core Team"
+- Ansible Core Team
-    - "Michael DeHaan"
+- Michael DeHaan
+'''
+
+EXAMPLES = r'''
+---
+- name: Asynchronous yum task
+  yum:
+    name: docker-io
+    state: installed
+  async: 1000
+  poll: 0
+  register: yum_sleeper
+
+- name: Wait for asynchronous job to end
+  async_status:
+    jid: '{{ yum_sleeper.ansible_job_id }}'
+  register: job_result
+  until: job_result.finished
+  retries: 30
+'''
+
+RETURN = r'''
+ansible_job_id:
+  description: The asynchronous job id
+  returned: success
+  type: str
+  sample: '360874038559.4169'
+finished:
+  description: Whether the asynchronous job has finished (C(1)) or not (C(0))
+  returned: success
+  type: int
+  sample: 1
+started:
+  description: Whether the asynchronous job has started (C(1)) or not (C(0))
+  returned: success
+  type: int
+  sample: 1
 '''
 
 import json
 import os
 
-from ansible.module_utils._text import to_native
 from ansible.module_utils.basic import AnsibleModule
 from ansible.module_utils.six import iteritems
+from ansible.module_utils._text import to_native
 
 
 def main():
 
     module = AnsibleModule(argument_spec=dict(
-        jid=dict(required=True),
+        jid=dict(type='str', required=True),
-        mode=dict(default='status', choices=['status', 'cleanup']),
+        mode=dict(type='str', default='status', choices=['cleanup', 'status']),
         # passed in from the async_status action plugin
-        _async_dir=dict(required=True, type='path'),
+        _async_dir=dict(type='path', required=True),
     ))
 
     mode = module.params['mode']

lib/ansible/modules/utilities/logic/async_wrapper.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
+# Copyright: (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>, and others
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function

lib/ansible/modules/utilities/logic/debug.py

@@ -1,62 +1,66 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright 2012 Dag Wieers <dag@wieers.com>
+# Copyright: (c) 2012 Dag Wieers <dag@wieers.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 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: debug
 short_description: Print statements during execution
 description:
-     - This module prints statements during execution and can be useful
+- This module prints statements during execution and can be useful
-       for debugging variables or expressions without necessarily halting
+  for debugging variables or expressions without necessarily halting
-       the playbook. Useful for debugging together with the 'when:' directive.
+  the playbook.
-     - This module is also supported for Windows targets.
+- Useful for debugging together with the 'when:' directive.
-version_added: "0.8"
+- This module is also supported for Windows targets.
+version_added: '0.8'
 options:
   msg:
     description:
-      - The customized message that is printed. If omitted, prints a generic
+    - The customized message that is printed. If omitted, prints a generic message.
-        message.
+    type: str
-    required: false
+    default: 'Hello world!'
-    default: "Hello world!"
   var:
     description:
-      - A variable name to debug.  Mutually exclusive with the 'msg' option.
+    - A variable name to debug.
-      - Be aware that this option already runs in Jinja2 context and has an implicit ``{{ }}`` wrapping,
+    - Mutually exclusive with the C(msg) option.
-        so you should not be using Jinja2 delimiters unless you are looking for double interpolation.
+    - Be aware that this option already runs in Jinja2 context and has an implicit C({{ }}) wrapping,
+      so you should not be using Jinja2 delimiters unless you are looking for double interpolation.
+    type: str
   verbosity:
     description:
-      - A number that controls when the debug is run, if you set to 3 it will only run debug when -vvv or above
+    - A number that controls when the debug is run, if you set to 3 it will only run debug when -vvv or above
-    required: False
+    type: int
     default: 0
-    version_added: "2.1"
+    version_added: '2.1'
 notes:
     - This module is also supported for Windows targets.
+seealso:
+- module: assert
+- module: fail
 author:
-    - "Dag Wieers (@dagwieers)"
+- Dag Wieers (@dagwieers)
-    - "Michael DeHaan"
+- Michael DeHaan
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
 # Example that prints the loopback address and gateway for each host
 - debug:
-    msg: "System {{ inventory_hostname }} has uuid {{ ansible_product_uuid }}"
+    msg: System {{ inventory_hostname }} has uuid {{ ansible_product_uuid }}
 
 - debug:
-    msg: "System {{ inventory_hostname }} has gateway {{ ansible_default_ipv4.gateway }}"
+    msg: System {{ inventory_hostname }} has gateway {{ ansible_default_ipv4.gateway }}
   when: ansible_default_ipv4.gateway is defined
 
+# Example that prints return information from the previous task
 - shell: /usr/bin/uptime
   register: result
 
@@ -69,9 +73,9 @@ EXAMPLES = '''
     var: hostvars[inventory_hostname]
     verbosity: 4
 
-# Example that prints two lines of messages, but only if there's an environment value set
+# Example that prints two lines of messages, but only if there is an environment value set
 - debug:
     msg:
-      - "Provisioning based on YOUR_KEY which is: '{{ lookup('env', 'YOUR_KEY') }}"
+    - "Provisioning based on YOUR_KEY which is: {{ lookup('env', 'YOUR_KEY') }}"
-      - "These servers were built using the password of '{{ password_used }}'. Please retain this for later use."
+    - "These servers were built using the password of '{{ password_used }}'. Please retain this for later use."
 '''

lib/ansible/modules/utilities/logic/fail.py

@@ -1,43 +1,45 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
 
-# Copyright 2012 Dag Wieers <dag@wieers.com>
+# Copyright: (c) 2012, Dag Wieers <dag@wieers.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 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: fail
 short_description: Fail with custom message
 description:
-     - This module fails the progress with a custom message. It can be
+- This module fails the progress with a custom message.
-       useful for bailing out when a certain condition is met using C(when).
+- It can be useful for bailing out when a certain condition is met using C(when).
-     - This module is also supported for Windows targets.
+- This module is also supported for Windows targets.
 version_added: "0.8"
 options:
   msg:
     description:
-      - The customized message used for failing execution. If omitted,
+    - The customized message used for failing execution.
-        fail will simply bail out with a generic message.
+    - If omitted, fail will simply bail out with a generic message.
-    required: false
+    type: str
-    default: "'Failed as requested from task'"
+    default: Failed as requested from task
 notes:
     - This module is also supported for Windows targets.
-
+seealso:
-author: "Dag Wieers (@dagwieers)"
+- module: assert
+- module: debug
+- module: meta
+author:
+- Dag Wieers (@dagwieers)
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
 # Example playbook using fail and when together
 - fail:
-    msg: "The system may not be provisioned according to the CMDB status."
+    msg: The system may not be provisioned according to the CMDB status.
   when: cmdb_status != "to-be-staged"
 '''

lib/ansible/modules/utilities/logic/import_playbook.py

@@ -1,27 +1,27 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
+
 # Copyright:  Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {
     'metadata_version': '1.1',
     'status': ['preview'],
     'supported_by': 'core'
 }
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = '''
 ---
 author: Ansible Core Team (@ansible)
 module: import_playbook
 short_description: Import a playbook
 description:
   - Includes a file with a list of plays to be executed.
-  - Files with a list of plays can only be included at the top level. You cannot use this action inside a play.
+  - Files with a list of plays can only be included at the top level.
+  - You cannot use this action inside a play.
 version_added: "2.4"
 options:
   free-form:
@@ -29,9 +29,16 @@ options:
       - The name of the imported playbook is specified directly without any other option.
 notes:
   - This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
+seealso:
+- module: import_role
+- module: import_tasks
+- module: include_role
+- module: include_tasks
+- ref: playbooks_reuse_includes
+  description: More information related to including and importing playbooks, roles and tasks.
 '''
 
-EXAMPLES = """
+EXAMPLES = r'''
 - hosts: localhost
   tasks:
     - debug:
@@ -49,8 +56,8 @@ EXAMPLES = """
 
     - name: This fails because I'm inside a play already
       import_playbook: stuff.yaml
-"""
+'''
 
-RETURN = """
+RETURN = r'''
 # This module does not return anything except plays to execute.
-"""
+'''

lib/ansible/modules/utilities/logic/import_role.py

@@ -6,62 +6,71 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {
     'metadata_version': '1.1',
     'status': ['stableinterface'],
     'supported_by': 'core'
 }
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = '''
 ---
 author: Ansible Core Team (@ansible)
 module: import_role
 short_description: Import a role into a play
 description:
-  - Much like the `roles:` keyword, this task loads a role, but it allows you to control it when the role tasks run in
+  - Much like the C(roles:) keyword, this task loads a role, but it allows you to control it when the role tasks run in
     between other tasks of the play.
   - Most keywords, loops and conditionals will only be applied to the imported tasks, not to this statement itself. If
-    you want the opposite behavior, use M(include_role) instead. To better understand the difference you can read
+    you want the opposite behavior, use M(include_role) instead.
-    the L(Including and Importing Guide,../user_guide/playbooks_reuse_includes.html).
+version_added: '2.4'
-version_added: "2.4"
 options:
   name:
     description:
       - The name of the role to be executed.
-    required: True
+    type: str
+    required: true
   tasks_from:
     description:
       - File to load from a role's C(tasks/) directory.
+    type: str
     default: main
   vars_from:
     description:
       - File to load from a role's C(vars/) directory.
+    type: str
     default: main
   defaults_from:
     description:
       - File to load from a role's C(defaults/) directory.
+    type: str
     default: main
   allow_duplicates:
     description:
       - Overrides the role's metadata setting to allow using a role more than once with the same parameters.
     type: bool
-    default: 'yes'
+    default: yes
   handlers_from:
     description:
       - File to load from a role's C(handlers/) directory.
+    type: str
     default: main
     version_added: '2.8'
 notes:
   - Handlers are made available to the whole play.
-  - "Since Ansible 2.7: variables defined in C(vars) and C(defaults) for the role are exposed at playbook parsing time.
+  - Since Ansible 2.7 variables defined in C(vars) and C(defaults) for the role are exposed at playbook parsing time.
     Due to this, these variables will be accessible to roles and tasks executed before the location of the
-    C(import_role) task."
+    M(import_role) task.
-  - Unlike C(include_role) variable exposure is not configurable, and will always be exposed.
+  - Unlike M(include_role) variable exposure is not configurable, and will always be exposed.
+seealso:
+- module: import_playbook
+- module: import_tasks
+- module: include_role
+- module: include_tasks
+- ref: playbooks_reuse_includes
+  description: More information related to including and importing playbooks, roles and tasks.
 '''
 
-EXAMPLES = """
+EXAMPLES = r'''
 - hosts: all
   tasks:
     - import_role:
@@ -82,8 +91,8 @@ EXAMPLES = """
       import_role:
         name: myrole
       when: not idontwanttorun
-"""
+'''
 
-RETURN = """
+RETURN = r'''
 # This module does not return anything except tasks to execute.
-"""
+'''

lib/ansible/modules/utilities/logic/import_tasks.py

@@ -1,20 +1,19 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
+
 # Copyright:  Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {
     'metadata_version': '1.1',
     'status': ['stableinterface'],
     'supported_by': 'core'
 }
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = '''
 ---
 author: Ansible Core Team (@ansible)
 module: import_tasks
@@ -26,13 +25,20 @@ options:
   free-form:
     description:
       - The name of the imported file is specified directly without any other option.
-      - Most keywords, including loops and conditionals, only applied to the imported tasks, not to this statement
+      - Most keywords, including loops and conditionals, only applied to the imported tasks, not to this statement itself.
-        itself. If you need any of those to apply, use M(include_tasks) instead.
+      - If you need any of those to apply, use M(include_tasks) instead.
 notes:
   - This is a core feature of Ansible, rather than a module, and cannot be overridden like a module.
+seealso:
+- module: import_playbook
+- module: import_role
+- module: include_role
+- module: include_tasks
+- ref: playbooks_reuse_includes
+  description: More information related to including and importing playbooks, roles and tasks.
 '''
 
-EXAMPLES = """
+EXAMPLES = r'''
 - hosts: all
   tasks:
     - debug:
@@ -52,8 +58,8 @@ EXAMPLES = """
     - name: Apply conditional to all imported tasks
       import_tasks: stuff.yaml
       when: hostvar is defined
-"""
+'''
 
-RETURN = """
+RETURN = r'''
 # This module does not return anything except tasks to execute.
-"""
+'''

lib/ansible/modules/utilities/logic/include.py

@@ -1,20 +1,19 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
+
 # Copyright:  Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {
     'metadata_version': '1.1',
     'status': ['preview'],
     'supported_by': 'core'
 }
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = '''
 ---
 author: Ansible Core Team (@ansible)
 module: include
@@ -23,11 +22,11 @@ description:
   - Includes a file with a list of plays or tasks to be executed in the current playbook.
   - Files with a list of plays can only be included at the top level. Lists of tasks can only be included where tasks
     normally run (in play).
-  - Before Ansible version 2.0, all includes were 'static' and were executed when the play was compiled.
+  - Before Ansible 2.0, all includes were 'static' and were executed when the play was compiled.
   - Static includes are not subject to most directives. For example, loops or conditionals are applied instead to each
     inherited task.
   - Since Ansible 2.0, task includes are dynamic and behave more like real tasks. This means they can be looped,
-    skipped and use variables from any source. Ansible tries to auto detect this, but you can use the `static`
+    skipped and use variables from any source. Ansible tries to auto detect this, but you can use the C(static)
     directive (which was added in Ansible 2.1) to bypass autodetection.
   - This module is also supported for Windows targets.
 version_added: "0.6"
@@ -40,10 +39,18 @@ notes:
   - Include has some unintuitive behaviours depending on if it is running in a static or dynamic in play or in playbook context,
     in an effort to clarify behaviours we are moving to a new set modules (M(include_tasks), M(include_role), M(import_playbook), M(import_tasks))
     that have well established and clear behaviours.
-    This module will still be supported for some time but we are looking at deprecating it in the near future.
+  - B(This module will still be supported for some time but we are looking at deprecating it in the near future.)
+seealso:
+- module: import_playbook
+- module: import_role
+- module: import_tasks
+- module: include_role
+- module: include_tasks
+- ref: playbooks_reuse_includes
+  description: More information related to including and importing playbooks, roles and tasks.
 '''
 
-EXAMPLES = """
+EXAMPLES = r'''
 - hosts: localhost
   tasks:
     - debug:
@@ -73,8 +80,8 @@ EXAMPLES = """
       include: "{{ hostvar }}.yaml"
       static: no
       when: hostvar is defined
-"""
+'''
 
-RETURN = """
+RETURN = r'''
 # This module does not return anything except plays or tasks to execute.
-"""
+'''

lib/ansible/modules/utilities/logic/include_role.py

@@ -1,27 +1,26 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
+
 # Copyright: Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {
     'metadata_version': '1.1',
     'status': ['stableinterface'],
     'supported_by': 'core'
 }
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = '''
 ---
 author: Ansible Core Team (@ansible)
 module: include_role
 short_description: Load and execute a role
 description:
-  - Loads and executes a role as a task dynamically. This frees roles from the `roles:` directive and allows them to be
+  - Loads and executes a role as a task dynamically.
-    treated more as tasks.
+  - This frees roles from the C(roles:) directive and allows them to be treated more as tasks.
   - Unlike M(import_role), most keywords, including loop, with_items, and conditionals, apply to this statement.
   - The do until loop is not supported on M(include_role).
   - This module is also supported for Windows targets.
@@ -34,24 +33,28 @@ options:
   name:
     description:
       - The name of the role to be executed.
+    type: str
     required: True
   tasks_from:
     description:
       - File to load from a role's C(tasks/) directory.
+    type: str
     default: main
   vars_from:
     description:
       - File to load from a role's C(vars/) directory.
+    type: str
     default: main
   defaults_from:
     description:
       - File to load from a role's C(defaults/) directory.
+    type: str
     default: main
   allow_duplicates:
     description:
       - Overrides the role's metadata setting to allow using a role more than once with the same parameters.
     type: bool
-    default: 'yes'
+    default: yes
   public:
     description:
       - This option dictates whether the role's C(vars) and C(defaults) are exposed to the playbook. If set to C(yes)
@@ -59,22 +62,30 @@ options:
         standard variable exposure for roles listed under the C(roles) header or C(import_role) as they are exposed at
         playbook parsing time, and available to earlier roles and tasks as well.
     type: bool
-    default: 'no'
+    default: no
     version_added: '2.7'
   handlers_from:
     description:
       - File to load from a role's C(handlers/) directory.
+    type: str
     default: main
     version_added: '2.8'
 notes:
   - Handlers are made available to the whole play.
   - Before Ansible 2.4, as with C(include), this task could be static or dynamic, If static, it implied that it won't
-    need templating, loops or conditionals and will show included tasks in the `--list` options. Ansible would try to
+    need templating, loops or conditionals and will show included tasks in the C(--list) options. Ansible would try to
-    autodetect what is needed, but you can set `static` to `yes` or `no` at task level to control this.
+    autodetect what is needed, but you can set C(static) to C(yes) or C(no) at task level to control this.
-  - After Ansible 2.4, you can use M(import_role) for 'static' behaviour and this action for 'dynamic' one.
+  - After Ansible 2.4, you can use M(import_role) for C(static) behaviour and this action for C(dynamic) one.
+seealso:
+- module: import_playbook
+- module: import_role
+- module: import_tasks
+- module: include_tasks
+- ref: playbooks_reuse_includes
+  description: More information related to including and importing playbooks, roles and tasks.
 '''
 
-EXAMPLES = """
+EXAMPLES = r'''
 - include_role:
     name: myrole
 
@@ -111,8 +122,8 @@ EXAMPLES = """
         - install
   tags:
     - always
-"""
+'''
 
-RETURN = """
+RETURN = r'''
 # This module does not return anything except tasks to execute.
-"""
+'''

lib/ansible/modules/utilities/logic/include_tasks.py

@@ -1,37 +1,38 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
+
 # Copyright:  Ansible Project
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {
     'metadata_version': '1.1',
     'status': ['stableinterface'],
     'supported_by': 'core'
 }
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = '''
 ---
 author: Ansible Core Team (@ansible)
 module: include_tasks
 short_description: Dynamically include a task list
 description:
   - Includes a file with a list of tasks to be executed in the current playbook.
-version_added: "2.4"
+version_added: '2.4'
 options:
   file:
     description:
       - The name of the imported file is specified directly without any other option.
       - Unlike M(import_tasks), most keywords, including loop, with_items, and conditionals, apply to this statement.
       - The do until loop is not supported on M(include_tasks).
+    type: str
     version_added: '2.7'
   apply:
     description:
       - Accepts a hash of task keywords (e.g. C(tags), C(become)) that will be applied to the tasks within the include.
+    type: str
     version_added: '2.7'
   free-form:
     description:
@@ -40,9 +41,16 @@ options:
         of specifying an argument of I(file).
 notes:
   - This is a core feature of the Ansible, rather than a module, and cannot be overridden like a module.
+seealso:
+- module: import_playbook
+- module: import_role
+- module: import_tasks
+- module: include_role
+- ref: playbooks_reuse_includes
+  description: More information related to including and importing playbooks, roles and tasks.
 '''
 
-EXAMPLES = """
+EXAMPLES = r'''
 - hosts: all
   tasks:
     - debug:
@@ -80,8 +88,8 @@ EXAMPLES = """
         - install
   tags:
     - always
-"""
+'''
 
-RETURN = """
+RETURN = r'''
 # This module does not return anything except tasks to execute.
-"""
+'''

lib/ansible/modules/utilities/logic/include_vars.py

@@ -1,18 +1,18 @@
+#!/usr/bin/python
 # -*- coding: utf-8 -*-
+
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {
     'metadata_version': '1.1',
     'status': ['stableinterface'],
     'supported_by': 'core'
 }
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = '''
 ---
 author: Allen Sanabria (@linuxdynasty)
 module: include_vars
@@ -22,58 +22,72 @@ description:
   - If loading a directory, the files are sorted alphabetically before being loaded.
   - This module is also supported for Windows targets.
   - To assign included variables to a different host than C(inventory_hostname),
-    use C(delegate_to) and set L(delegate_facts=True,../user_guide/playbooks_delegate.html#delegated-facts).
+    use C(delegate_to) and set C(delegate_facts=yes).
 version_added: "1.4"
 options:
   file:
-    version_added: "2.2"
     description:
       - The file name from which variables should be loaded.
       - If the path is relative, it will look for the file in vars/ subdirectory of a role or relative to playbook.
-  dir:
+    type: path
     version_added: "2.2"
+  dir:
     description:
       - The directory name from which the variables should be loaded.
       - If the path is relative and the task is inside a role, it will look inside the role's vars/ subdirectory.
       - If the path is relative and not inside a role, it will be parsed relative to the playbook.
+    type: path
+    version_added: "2.2"
   name:
-    version_added: "2.2"
     description:
-      - The name of a variable into which assign the included vars. If omitted (null) they will be made top level vars.
+      - The name of a variable into which assign the included vars.
-  depth:
+      - If omitted (null) they will be made top level vars.
+    type: str
     version_added: "2.2"
+  depth:
     description:
       - When using C(dir), this module will, by default, recursively go through each sub directory and load up the
         variables. By explicitly setting the depth, this module will only go as deep as the depth.
+    type: int
     default: 0
-  files_matching:
     version_added: "2.2"
+  files_matching:
     description:
       - Limit the files that are loaded within any directory to this regular expression.
-  ignore_files:
+    type: str
     version_added: "2.2"
+  ignore_files:
     description:
       - List of file names to ignore.
+    type: list
+    version_added: "2.2"
   extensions:
-    version_added: "2.3"
     description:
       - List of file extensions to read when using C(dir).
-    default: [yaml, yml, json]
+    type: list
+    default: [ json, yaml, yml ]
+    version_added: "2.3"
   ignore_unknown_extensions:
-    version_added: "2.7"
     description:
-      - Ignore unknown file extensions within the directory. This allows users to specify a directory containing vars files
+      - Ignore unknown file extensions within the directory.
-        that are intermingled with non vars files extension types (For example, a directory with a README in it and vars files)
+      - This allows users to specify a directory containing vars files that are intermingled with non-vars files extension types
-    default: False
+        (e.g. a directory with a README in it and vars files).
+    type: bool
+    default: no
+    version_added: "2.7"
   free-form:
     description:
       - This module allows you to specify the 'file' option directly without any other options.
-        There is no 'free-form' option, this is just an indicator, see example below.
+      - There is no 'free-form' option, this is just an indicator, see example below.
 notes:
   - This module is also supported for Windows targets.
+seealso:
+- module: set_fact
+- ref: playbooks_delegation
+  description: More information related to task delegation.
 '''
 
-EXAMPLES = """
+EXAMPLES = r'''
 - name: Include vars of stuff.yaml into the 'stuff' variable (2.2).
   include_vars:
     file: stuff.yaml
@@ -129,9 +143,9 @@ EXAMPLES = """
     dir: vars
     ignore_unknown_extensions: True
     extensions: ['', 'yaml', 'yml', 'json']
-"""
+'''
 
-RETURN = '''
+RETURN = r'''
 ansible_facts:
   description: Variables that were included and their values
   returned: success
@@ -141,6 +155,6 @@ ansible_included_var_files:
   description: A list of files that were successfully included
   returned: success
   type: list
-  sample: [ '/path/to/file.yaml', '/path/to/file.json' ]
+  sample: [ /path/to/file.json, /path/to/file.yaml ]
-  version_added: 2.4
+  version_added: '2.4'
 '''

lib/ansible/modules/utilities/logic/set_fact.py

@@ -7,25 +7,22 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = '''
 ---
-author:
-- Dag Wieers (@dagwieers)
 module: set_fact
 short_description: Set host facts from a task
+version_added: "1.2"
 description:
-    - This module allows setting new variables.  Variables are set on a host-by-host basis just like facts discovered by the setup module.
+    - This module allows setting new variables.
+    - Variables are set on a host-by-host basis just like facts discovered by the setup module.
     - These variables will be available to subsequent plays during an ansible-playbook run.
     - Set C(cacheable) to C(yes) to save variables across executions
       using a fact cache. Variables created with set_fact have different precedence depending on whether they are or are not cached.
     - Per the standard Ansible variable precedence rules, many other types of variables have a higher priority, so this value may be overridden.
-      See L(Variable Precedence Guide,../user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable) for more information.
     - This module is also supported for Windows targets.
 options:
   key_value:
@@ -42,19 +39,24 @@ options:
         https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable
       - "This actually creates 2 copies of the variable, a normal 'set_fact' host variable with high precedence and
         a lower 'ansible_fact' one that is available for persistance via the facts cache plugin.
-        This creates a possibly confusing interaction with ``meta: clear_facts`` as it will remove the 'ansible_fact' but not the host variable."
+        This creates a possibly confusing interaction with C(meta: clear_facts) as it will remove the 'ansible_fact' but not the host variable."
     type: bool
-    default: 'no'
+    default: no
     version_added: "2.4"
-version_added: "1.2"
 notes:
-    - "The `var=value` notation can only create strings or booleans.
+    - "The C(var=value) notation can only create strings or booleans.
-      If you want to create lists/arrays or dictionary/hashes use `var: [val1, val2]`"
+      If you want to create lists/arrays or dictionary/hashes use C(var: [val1, val2])."
+    - Since 'cacheable' is now a module param, 'cacheable' is no longer a valid fact name as of Ansible 2.4.
     - This module is also supported for Windows targets.
-    - Since 'cacheable' is now a module param, 'cacheable' is no longer a valid fact name as of 2.4.
+seealso:
+- module: include_vars
+- ref: ansible_variable_precedence
+  description: More information related to variable precedence and which type of variable wins over others.
+author:
+- Dag Wieers (@dagwieers)
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
 # Example setting host facts using key=value pairs, note that this always creates strings or booleans
 - set_fact: one_fact="something" other_fact="{{ local_var }}"
 
@@ -68,13 +70,13 @@ EXAMPLES = '''
 - set_fact:
     one_fact: something
     other_fact: "{{ local_var * 2 }}"
-    cacheable: true
+    cacheable: yes
 
-# As of 1.8, Ansible will convert boolean strings ('true', 'false', 'yes', 'no')
+# As of Ansible 1.8, Ansible will convert boolean strings ('true', 'false', 'yes', 'no')
 # to proper boolean values when using the key=value syntax, however it is still
 # recommended that booleans be set using the complex argument style:
 - set_fact:
-    one_fact: true
+    one_fact: yes
-    other_fact: false
+    other_fact: no
 
 '''

lib/ansible/modules/utilities/logic/set_stats.py

@@ -1,47 +1,47 @@
 #!/usr/bin/python
 # -*- coding: utf-8 -*-
-# Copyright 2016 Ansible RedHat, Inc
+
+# Copyright: (c) 2016, Ansible RedHat, Inc
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}
 
-
+DOCUMENTATION = r'''
-DOCUMENTATION = '''
 ---
-author: "Brian Coca (@bcoca)"
 module: set_stats
 short_description: Set stats for the current ansible run
 description:
      - This module allows setting/accumulating stats on the current ansible run, either per host or for all hosts in the run.
      - This module is also supported for Windows targets.
+author: Brian Coca (@bcoca)
 options:
   data:
     description:
-      - A dictionary of which each key represents a stat (or variable) you want to keep track of
+      - A dictionary of which each key represents a stat (or variable) you want to keep track of.
+    type: dict
     required: true
   per_host:
     description:
-        - boolean that indicates if the stats is per host or for all hosts in the run.
+        - whether the stats are per host or for all hosts in the run.
-    required: no
+    type: bool
     default: no
   aggregate:
     description:
-        - boolean that indicates if the provided value is aggregated to the existing stat C(yes) or will replace it C(no)
+        - Whether the provided value is aggregated to the existing stat C(yes) or will replace it C(no).
-    required: no
+    type: bool
     default: yes
 notes:
+    - In order for custom stats to be displayed, you must set C(show_custom_stats) in C(ansible.cfg) or C(ANSIBLE_SHOW_CUSTOM_STATS) to C(yes).
     - This module is also supported for Windows targets.
-    - In order for custom stats to be displayed, you must set C(show_custom_stats) in C(ansible.cfg) or C(ANSIBLE_SHOW_CUSTOM_STATS) to C(true).
 version_added: "2.3"
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
 # Aggregating packages_installed stat per host
 - set_stats:
     data:

lib/ansible/modules/utilities/logic/wait_for.py

@@ -7,7 +7,6 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
@@ -20,12 +19,12 @@ description:
      - You can wait for a set amount of time C(timeout), this is the default if nothing is specified or just C(timeout) is specified.
        This does not produce an error.
      - Waiting for a port to become available is useful for when services are not immediately available after their init scripts return
-       which is true of certain Java application servers. It is also useful when starting guests with the M(virt) module and
+       which is true of certain Java application servers.
-       needing to pause until they are ready.
+     - It is also useful when starting guests with the M(virt) module and needing to pause until they are ready.
      - This module can also be used to wait for a regex match a string to be present in a file.
-     - In 1.6 and later, this module can also be used to wait for a file to be available or
+     - In Ansible 1.6 and later, this module can also be used to wait for a file to be available or
        absent on the filesystem.
-     - In 1.8 and later, this module can also be used to wait for active connections to be closed before continuing, useful if a node
+     - In Ansible 1.8 and later, this module can also be used to wait for active connections to be closed before continuing, useful if a node
        is being rotated out of a load balancer pool.
      - For Windows targets, use the M(win_wait_for) module instead.
 version_added: "0.7"
@@ -33,27 +32,33 @@ options:
   host:
     description:
       - A resolvable hostname or IP address to wait for.
-    default: "127.0.0.1"
+    type: str
+    default: 127.0.0.1
   timeout:
     description:
       - Maximum number of seconds to wait for, when used with another condition it will force an error.
       - When used without other conditions it is equivalent of just sleeping.
+    type: int
     default: 300
   connect_timeout:
     description:
       - Maximum number of seconds to wait for a connection to happen before closing and retrying.
+    type: int
     default: 5
   delay:
     description:
       - Number of seconds to wait before starting to poll.
+    type: int
     default: 0
   port:
     description:
       - Port number to poll.
       - C(path) and C(port) are mutually exclusive parameters.
+    type: int
   active_connection_states:
     description:
       - The list of TCP connection states which are counted as active connections.
+    type: list
     default: [ ESTABLISHED, FIN_WAIT1, FIN_WAIT2, SYN_RECV, SYN_SENT, TIME_WAIT ]
     version_added: "2.3"
   state:
@@ -62,35 +67,42 @@ options:
       - When checking a port C(started) will ensure the port is open, C(stopped) will check that it is closed, C(drained) will check for active connections.
       - When checking for a file or a search string C(present) or C(started) will ensure that the file or string is present before continuing,
         C(absent) will check that file is absent or removed.
+    type: str
     choices: [ absent, drained, present, started, stopped ]
     default: started
   path:
-    version_added: "1.4"
     description:
       - Path to a file on the filesystem that must exist before continuing.
       - C(path) and C(port) are mutually exclusive parameters.
-  search_regex:
+    type: path
     version_added: "1.4"
+  search_regex:
     description:
       - Can be used to match a string in either a file or a socket connection.
       - Defaults to a multiline regex.
+    type: str
+    version_added: "1.4"
   exclude_hosts:
-    version_added: "1.8"
     description:
       - List of hosts or IPs to ignore when looking for active TCP connections for C(drained) state.
+    type: list
+    version_added: "1.8"
   sleep:
-    version_added: "2.3"
-    default: 1
     description:
-      - Number of seconds to sleep between checks, before 2.3 this was hardcoded to 1 second.
+      - Number of seconds to sleep between checks.
+      - Before Ansible 2.3 this was hardcoded to 1 second.
+    type: int
+    default: 1
+    version_added: "2.3"
   msg:
-    version_added: "2.4"
     description:
       - This overrides the normal error message from a failure to meet the required conditions.
+    type: str
+    version_added: "2.4"
 notes:
-  - The ability to use search_regex with a port connection was added in 1.7.
+  - The ability to use search_regex with a port connection was added in Ansible 1.7.
-  - Prior to 2.4, testing for the absence of a directory or UNIX socket did not work correctly.
+  - Prior to Ansible 2.4, testing for the absence of a directory or UNIX socket did not work correctly.
-  - Prior to 2.4, testing for the presence of a file did not work correctly if the remote user did not have read access to that file.
+  - Prior to Ansible 2.4, testing for the presence of a file did not work correctly if the remote user did not have read access to that file.
   - Under some circumstances when using mandatory access control, a path may always be treated as being absent even if it exists, but
     can't be modified or created by the remote user either.
   - When waiting for a path, symbolic links will be followed.  Many other modules that manipulate files do not follow symbolic links,
@@ -107,7 +119,8 @@ author:
 
 EXAMPLES = r'''
 - name: sleep for 300 seconds and continue with play
-  wait_for: timeout=300
+  wait_for:
+    timeout: 300
   delegate_to: localhost
 
 - name: Wait for port 8000 to become open on the host, don't start checking for 10 seconds
@@ -162,7 +175,7 @@ EXAMPLES = r'''
     state: present
     msg: Timeout to find file /tmp/foo
 
-# Don't assume the inventory_hostname is resolvable and delay 10 seconds at start
+# Do not assume the inventory_hostname is resolvable and delay 10 seconds at start
 - name: Wait 300 seconds for port 22 to become open and contain "OpenSSH"
   wait_for:
     port: 22

lib/ansible/modules/utilities/logic/wait_for_connection.py

@@ -7,12 +7,10 @@
 from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
-
 ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['stableinterface'],
                     'supported_by': 'core'}
 
-
 DOCUMENTATION = r'''
 ---
 module: wait_for_connection
@@ -23,23 +21,27 @@ description:
 - Tests the transport connection every C(sleep) seconds.
 - This module makes use of internal ansible transport (and configuration) and the ping/win_ping module to guarantee correct end-to-end functioning.
 - This module is also supported for Windows targets.
-version_added: "2.3"
+version_added: '2.3'
 options:
   connect_timeout:
     description:
-      - Maximum number of seconds to wait for a connection to happen before closing and retrying.
+    - Maximum number of seconds to wait for a connection to happen before closing and retrying.
+    type: int
     default: 5
   delay:
     description:
-      - Number of seconds to wait before starting to poll.
+    - Number of seconds to wait before starting to poll.
+    type: int
     default: 0
   sleep:
-    default: 1
     description:
-      - Number of seconds to sleep between checks.
+    - Number of seconds to sleep between checks.
+    type: int
+    default: 1
   timeout:
     description:
-      - Maximum number of seconds to wait for.
+    - Maximum number of seconds to wait for.
+    type: int
     default: 600
 notes:
 - This module is also supported for Windows targets.
@@ -103,6 +105,6 @@ RETURN = r'''
 elapsed:
   description: The number of seconds that elapsed waiting for the connection to appear.
   returned: always
-  type: int
+  type: float
-  sample: 23
+  sample: 23.1
 '''