fixed RETURN docs for modules (#24011)

* fixed RETURN docs for remaining modules

* updated proxymysql_mysql_users 'sample' to yaml dict

* fixed whitespace errors

lib/ansible/modules/clustering/kubernetes.py

@@ -138,7 +138,7 @@ RETURN = '''
 api_response:
     description: Raw response from Kubernetes API, content varies with API.
     returned: success
-    type: dictionary
+    type: complex
     contains:
         apiVersion: "v1"
         kind: "Namespace"

lib/ansible/modules/clustering/pacemaker_cluster.py

@@ -66,17 +66,20 @@ EXAMPLES = '''
 '''
 
 RETURN = '''
-change:
+changed:
     description: True if the cluster state has changed
     type: bool
+    returned: always
 out:
     description: The output of the current state of the cluster. It return a
                  list of the nodes state.
     type: string
     sample: 'out: [["  overcloud-controller-0", " Online"]]}'
+    returned: always
 rc:
     description: exit code of the module
     type: bool
+    returned: always
 '''
 
 import time

lib/ansible/modules/commands/shell.py

@@ -171,6 +171,6 @@ rc:
 stdout_lines:
     description: The command standard output split in lines
     returned: always
-    type: list of strings
+    type: list
     sample: [u'Clustering node rabbit@slave1 with rabbit@master ...']
 '''

lib/ansible/modules/crypto/openssl_csr.py

@@ -141,23 +141,17 @@ EXAMPLES = '''
 RETURN = '''
 csr:
     description: Path to the generated Certificate Signing Request
-    returned:
+    returned: changed or success
-        - changed
-        - success
     type: string
     sample: /etc/ssl/csr/www.ansible.com.csr
 subject:
     description: A dictionnary of the subject attached to the CSR
-    returned:
+    returned: changed or success
-        - changed
-        - success
     type: list
     sample: {'CN': 'www.ansible.com', 'O': 'Ansible'}
 subjectAltName:
     description: The alternative names this CSR is valid for
-    returned:
+    returned: changed or success
-        - changed
-        - success
     type: string
     sample: 'DNS:www.ansible.com,DNS:m.ansible.com'
 '''

lib/ansible/modules/crypto/openssl_privatekey.py

@@ -88,23 +88,17 @@ EXAMPLES = '''
 RETURN = '''
 size:
     description: Size (in bits) of the TLS/SSL private key
-    returned:
+    returned: changed or success
-        - changed
+    type: int
-        - success
-    type: integer
     sample: 4096
 type:
     description: Algorithm used to generate the TLS/SSL private key
-    returned:
+    returned: changed or success
-        - changed
-        - success
     type: string
     sample: RSA
 filename:
     description: Path to the generated TLS/SSL private key file
-    returned:
+    returned: changed or success
-        - changed
-        - success
     type: string
     sample: /etc/ssl/private/ansible.com.pem
 '''

lib/ansible/modules/crypto/openssl_publickey.py

@@ -78,16 +78,12 @@ EXAMPLES = '''
 RETURN = '''
 privatekey:
     description: Path to the TLS/SSL private key the public key was generated from
-    returned:
+    returned: changed or success
-        - changed
-        - success
     type: string
     sample: /etc/ssl/private/ansible.com.pem
 filename:
     description: Path to the generated TLS/SSL public key file
-    returned:
+    returned: changed or success
-        - changed
-        - success
     type: string
     sample: /etc/ssl/public/ansible.com.pem
 '''

lib/ansible/modules/database/proxysql/proxysql_mysql_users.py

@@ -148,26 +148,24 @@ stdout:
     returned: On create/update will return the newly modified user, on delete
               it will return the deleted record.
     type: dict
-    sample": {
+    sample:
-        "changed": true,
+        changed: true
-        "msg": "Added user to mysql_users",
+        msg: Added user to mysql_users
-        "state": "present",
+        state: present
-        "user": {
+        user:
-            "active": "1",
+            active: 1
-            "backend": "1",
+            backend: 1
-            "default_hostgroup": "1",
+            default_hostgroup: 1
-            "default_schema": null,
+            default_schema: null
-            "fast_forward": "0",
+            fast_forward: 0
-            "frontend": "1",
+            frontend: 1
-            "max_connections": "10000",
+            max_connections: 10000
-            "password": "VALUE_SPECIFIED_IN_NO_LOG_PARAMETER",
+            password: VALUE_SPECIFIED_IN_NO_LOG_PARAMETER
-            "schema_locked": "0",
+            schema_locked: 0
-            "transaction_persistent": "0",
+            transaction_persistent: 0
-            "use_ssl": "0",
+            use_ssl: 0
-            "username": "guest_ro"
+            username: guest_ro
-        },
+        username: guest_ro
-        "username": "guest_ro"
-    }
 '''
 
 ANSIBLE_METADATA = {'metadata_version': '1.0',

lib/ansible/modules/files/archive.py

@@ -107,9 +107,11 @@ archived:
 arcroot:
     description: The archive root.
     type: string
+    returned: always
 expanded_paths:
     description: The list of matching paths from paths argument.
     type: list
+    returned: always
 '''
 
 import os

lib/ansible/modules/files/find.py

@@ -156,7 +156,7 @@ RETURN = '''
 files:
     description: all matches found with the specified criteria (see stat module for full output of each dictionary)
     returned: success
-    type: list of dictionaries
+    type: list
     sample: [
         { path: "/var/tmp/test1",
           mode: "0644",

lib/ansible/modules/files/stat.py

@@ -140,7 +140,7 @@ RETURN = '''
 stat:
     description: dictionary containing all the stat data, some platforms might add additional fields
     returned: success
-    type: dictionary
+    type: complex
     contains:
         exists:
             description: if the destination path actually exists or not

lib/ansible/modules/monitoring/logicmonitor_facts.py

@@ -112,7 +112,7 @@ RETURN = '''
     ansible_facts:
         description: LogicMonitor properties set for the specified object
         returned: success
-        type: list of dicts containing name/value pairs
+        type: list
         example: >
             {
                 "name": "dc",

lib/ansible/modules/packaging/os/apt.py

@@ -212,7 +212,7 @@ cache_updated:
 cache_update_time:
     description: time of the last cache update (0 if unknown)
     returned: success, in some cases
-    type: datetime
+    type: int
     sample: 1425828348000
 stdout:
     description: output from apt

lib/ansible/modules/packaging/os/pacman.py

@@ -96,7 +96,7 @@ RETURN = '''
 packages:
     description: a list of packages that have been changed
     returned: when upgrade is set to yes
-    type: list of strings
+    type: list
     sample: ['package', 'other-package']
 '''
 

lib/ansible/modules/packaging/os/xbps.py

@@ -94,6 +94,7 @@ packages:
     description: Packages that are affected/would be affected
     type: list
     sample: ["ansible"]
+    returned: success
 '''
 
 

lib/ansible/modules/remote_management/hpilo/hpilo_facts.py

@@ -85,7 +85,7 @@ hw_bios_version:
 hw_ethX:
     description: Interface information (for each interface)
     returned: always
-    type: dictionary of information (macaddress)
+    type: dictionary
     sample:
       - macaddress: 00:11:22:33:44:55
         macaddress_dash: 00-11-22-33-44-55
@@ -93,7 +93,7 @@ hw_ethX:
 hw_eth_ilo:
     description: Interface information (for the iLO network interface)
     returned: always
-    type: dictionary of information (macaddress)
+    type: dictionary
     sample:
       - macaddress: 00:11:22:33:44:BA
       - macaddress_dash: 00-11-22-33-44-BA

lib/ansible/modules/storage/netapp/netapp_e_facts.py

@@ -67,7 +67,10 @@ EXAMPLES = """
 """
 
 RETURN = """
-msg: Gathered facts for <StorageArrayId>.
+msg:
+    description: Gathered facts for <StorageArrayId>.
+    returned: always
+    type: string
 """
 import json
 

lib/ansible/modules/storage/netapp/netapp_e_lun_mapping.py

@@ -98,8 +98,11 @@ EXAMPLES = '''
         api_password: "{{ netapp_api_password }}"
 '''
 RETURN = '''
-msg: Mapping exists.
+msg:
-msg: Mapping removed.
+    description: Status of mapping
+    returned: always
+    type: string
+    sample: 'Mapping existing'
 '''
 import json
 

lib/ansible/modules/storage/netapp/netapp_e_snapshot_images.py

@@ -73,9 +73,16 @@ EXAMPLES = """
 """
 RETURN = """
 ---
-    changed: true
+    msg:
-    msg: "Created snapshot image"
+        description: State of operation
-    image_id: "3400000060080E5000299B640063074057BC5C5E "
+        type: string
+        returned: always
+        sample: "Created snapshot image"
+    image_id:
+        description: ID of snaphot image
+        type: string
+        returned: state == created
+        sample: "3400000060080E5000299B640063074057BC5C5E "
 """
 
 HEADERS = {

lib/ansible/modules/storage/netapp/netapp_e_storage_system.py

@@ -99,8 +99,11 @@ EXAMPLES = '''
 '''
 
 RETURN = '''
-msg: Storage system removed.
+msg:
-msg: Storage system added.
+    description: State of request
+    type: string
+    returned: always
+    sample: 'Storage system removed.'
 '''
 import json
 from datetime import datetime as dt, timedelta

lib/ansible/modules/storage/netapp/netapp_e_volume.py

@@ -134,12 +134,11 @@ EXAMPLES = '''
 '''
 RETURN = '''
 ---
-msg: "Standard volume [workload_vol_1] has been created."
+msg:
-msg: "Thin volume [workload_thin_vol] has been created."
+    description: State of volume
-msg: "Volume [workload_vol_1] has been expanded."
+    type: string
-msg: "Volume [workload_vol_1] has been deleted."
+    returned: always
-msg: "Volume [workload_vol_1] did not exist."
+    sample: "Standard volume [workload_vol_1] has been created."
-msg: "Volume [workload_vol_1] already exists."
 '''
 
 import json

lib/ansible/modules/storage/netapp/sf_snapshot_schedule_manager.py

@@ -139,7 +139,7 @@ RETURN = """
 schedule_id:
     description: Schedule ID of the newly created schedule
     returned: success
-
+    type: string
 """
 
 from ansible.module_utils.basic import AnsibleModule

lib/ansible/modules/system/aix_inittab.py

@@ -119,7 +119,7 @@ mgs:
     sample: changed inittab entry startmyservice
 changed:
     description: whether the inittab changed or not
-    return: always
+    returned: always
     type: boolean
     sample: true
 '''

lib/ansible/modules/system/authorized_key.py

@@ -170,42 +170,42 @@ key_option:
   description: Key options related to the key.
   returned: success
   type: string
-  sameple: null
+  sample: null
 keyfile:
   description: Path for authorzied key file.
   returned: success
   type: string
-  sameple: /home/user/.ssh/authorized_keys
+  sample: /home/user/.ssh/authorized_keys
 manage_dir:
   description: Whether this module managed the directory of the authorized key file.
   returned: success
   type: boolean
-  sameple: True
+  sample: True
 path:
   description: Alternate path to the authorized_keys file
   returned: success
   type: string
-  sameple: null
+  sample: null
 state:
   description: Whether the given key (with the given key_options) should or should not be in the file
   returned: success
   type: string
-  sameple: present
+  sample: present
 unique:
   description: Whether the key is unique
   returned: success
   type: boolean
-  sameple: false
+  sample: false
 user:
   description: The username on the remote host whose authorized_keys file will be modified
   returned: success
   type: string
-  sameple: user
+  sample: user
 validate_certs:
   description: This only applies if using a https url as the source of the keys. If set to C(no), the SSL certificates will not be validated.
   returned: success
   type: boolean
-  sameple: true
+  sample: true
 '''
 
 # Makes sure the public key line is present or absent in the user's .ssh/authorized_keys.

lib/ansible/modules/system/parted.py

@@ -112,7 +112,7 @@ RETURN = '''
 partition_info:
   description: Current partition information
   returned: success
-  type: dict
+  type: complex
   contains:
     device:
       description: Generic device information.

lib/ansible/modules/system/systemd.py

@@ -123,7 +123,7 @@ status:
     description: A dictionary with the key=value pairs returned from `systemctl show`
     returned: success
     type: complex
-    sample: {
+    contains: {
             "ActiveEnterTimestamp": "Sun 2016-05-15 18:28:49 EDT",
             "ActiveEnterTimestampMonotonic": "8135942",
             "ActiveExitTimestampMonotonic": "0",

lib/ansible/modules/system/timezone.py

@@ -65,7 +65,7 @@ diff:
   description: The differences about the given arguments.
   returned: success
   type: dictionary
-  contains:
+  sample:
     before:
       description: The values before change
       type: dict

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

@@ -78,12 +78,12 @@ start:
   description: Time when started pausing
   returned: always
   type: string
-  sample: 2017-02-23 14:35:07.298862
+  sample: "2017-02-23 14:35:07.298862"
 stop:
   description: Time when ended pausing
   returned: always
   type: string
-  sample: 2017-02-23 14:35:09.552594
+  sample: "2017-02-23 14:35:09.552594"
 delta:
   description: Time paused in seconds
   returned: always

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

@@ -105,6 +105,6 @@ RETURN = r'''
 elapsed:
   description: The number of seconds that elapsed waiting for the connection to appear.
   returned: always
-  type: integer
+  type: int
   sample: 23
 '''

lib/ansible/modules/web_infrastructure/ansible_tower/tower_job_list.py

@@ -66,7 +66,7 @@ count:
     description: Total count of objects return
     returned: success
     type: int
-    sampled: 51
+    sample: 51
 next:
     description: next page available for the listing
     returned: success

lib/ansible/modules/web_infrastructure/ansible_tower/tower_job_wait.py

@@ -76,12 +76,12 @@ started:
     description: timestamp of when the job started running
     returned: success
     type: string
-    sample: 2017-03-01T17:03:53.200234Z
+    sample: "2017-03-01T17:03:53.200234Z"
 finished:
     description: timestamp of when the job finished running
     returned: success
     type: string
-    sample: 2017-03-01T17:04:04.078782Z
+    sample: "2017-03-01T17:04:04.078782Z"
 status:
     description: current status of job
     returned: success

lib/ansible/modules/web_infrastructure/letsencrypt.py

@@ -137,11 +137,12 @@ RETURN = '''
 cert_days:
   description: the number of days the certificate remains valid.
   returned: success
+  type: int
 challenge_data:
   description: per domain / challenge type challenge data
   returned: changed
   type: dictionary
-  contains:
+  sample:
     resource:
       description: the challenge resource that must be created for validation
       returned: changed
@@ -156,7 +157,7 @@ authorizations:
   description: ACME authorization data.
   returned: changed
   type: list
-  contains:
+  sample:
       authorization:
         description: ACME authorization object. See https://tools.ietf.org/html/draft-ietf-acme-acme-02#section-6.1.2
         returned: success

lib/ansible/modules/windows/win_command.py

@@ -122,6 +122,6 @@ rc:
 stdout_lines:
     description: The command standard output split in lines
     returned: always
-    type: list of strings
+    type: list
     sample: [u'Clustering node rabbit@slave1 with rabbit@master ...']
 '''

lib/ansible/modules/windows/win_find.py

@@ -227,13 +227,13 @@ examined:
     sample: 10
 matched:
     description: The number of files/folders that match the criteria
-    returns: always
+    returned: always
     type: int
     sample: 2
 files:
     description: Information on the files/folders that match the criteria returned as a list of dictionary elements for each file matched
     returned: success
-    type: dictionary
+    type: complex
     contains:
         attributes:
             description: attributes of the file at path in raw form

lib/ansible/modules/windows/win_iis_webapppool.py

@@ -117,7 +117,7 @@ attributes:
 info:
   description: Information on current state of the Application Pool
   returned: success
-  type: dictionary
+  type: complex
   sample:
   contains:
     attributes:

lib/ansible/modules/windows/win_regmerge.py

@@ -84,7 +84,7 @@ compare_to_key_found:
 difference_count:
     description: number of differences between the registry and the file
     returned: changed
-    type: integer
+    type: int
     sample: 1
 compared:
     description: whether a comparison has taken place between the registry and the file

lib/ansible/modules/windows/win_service.py

@@ -246,7 +246,7 @@ start_mode:
     type: string
     sample: manual
 path:
-    description:
+    description: path to the service
     returned: success and service exists
     type: string
     sample: C:\Windows\system32\svchost.exe -k LocalServiceNoNetwork
@@ -268,11 +268,11 @@ desktop_interact:
 dependencies:
     description: A list of dependencies the service relies on
     returned: success and service exists
-    type: List
+    type: list
     sample: False
 depended_by:
     description: A list of dependencies this service relies on
     returned: success and service exists
-    type: List
+    type: list
     sample: False
 '''

lib/ansible/modules/windows/win_shell.py

@@ -130,6 +130,6 @@ rc:
 stdout_lines:
     description: The command standard output split in lines
     returned: always
-    type: list of strings
+    type: list
     sample: [u'Clustering node rabbit@slave1 with rabbit@master ...']
 '''

lib/ansible/modules/windows/win_stat.py

@@ -112,7 +112,7 @@ changed:
 stat:
     description: dictionary containing all the stat data
     returned: success
-    type: dictionary
+    type: complex
     contains:
         attributes:
             description: attributes of the file at path in raw form

lib/ansible/modules/windows/win_updates.py

@@ -103,7 +103,7 @@ reboot_required:
 updates:
     description: List of updates that were found/installed
     returned: success
-    type: dictionary
+    type: complex
     sample:
     contains:
         title:

lib/ansible/modules/windows/win_uri.py

@@ -130,7 +130,6 @@ body:
   returned: when body is specified
   type: string
   sample: '{"id":1}'
-  version_added: "2.3"
 status_code:
   description: The HTTP Status Code of the response.
   returned: success