fixed RETURN docs for modules (#24011)

* fixed RETURN docs for remaining modules * updated proxymysql_mysql_users 'sample' to yaml dict * fixed whitespace errors
2024-09-14 20:13:21 +02:00 · 2017-04-26 15:56:13 +01:00 · 2017-04-26 15:56:13 +01:00 · d1517f997a
commit d1517f997a
parent 9a0a7f78d7
40 changed files with 105 additions and 102 deletions
--- a/lib/ansible/modules/clustering/kubernetes.py
+++ b/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"
--- a/lib/ansible/modules/clustering/pacemaker_cluster.py
+++ b/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
--- a/lib/ansible/modules/commands/shell.py
+++ b/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 ...']
 '''
--- a/lib/ansible/modules/crypto/openssl_csr.py
+++ b/lib/ansible/modules/crypto/openssl_csr.py
@ -141,23 +141,17 @@ EXAMPLES = '''
 RETURN = '''
 csr:
    description: Path to the generated Certificate Signing Request
-    returned:
-        - changed
-        - success
+    returned: changed or success
    type: string
    sample: /etc/ssl/csr/www.ansible.com.csr
 subject:
    description: A dictionnary of the subject attached to the CSR
-    returned:
-        - changed
-        - success
+    returned: changed or success
    type: list
    sample: {'CN': 'www.ansible.com', 'O': 'Ansible'}
 subjectAltName:
    description: The alternative names this CSR is valid for
-    returned:
-        - changed
-        - success
+    returned: changed or success
    type: string
    sample: 'DNS:www.ansible.com,DNS:m.ansible.com'
 '''
--- a/lib/ansible/modules/crypto/openssl_privatekey.py
+++ b/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:
-        - changed
-        - success
-    type: integer
+    returned: changed or success
+    type: int
    sample: 4096
 type:
    description: Algorithm used to generate the TLS/SSL private key
-    returned:
-        - changed
-        - success
+    returned: changed or success
    type: string
    sample: RSA
 filename:
    description: Path to the generated TLS/SSL private key file
-    returned:
-        - changed
-        - success
+    returned: changed or success
    type: string
    sample: /etc/ssl/private/ansible.com.pem
 '''
--- a/lib/ansible/modules/crypto/openssl_publickey.py
+++ b/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:
-        - changed
-        - success
+    returned: changed or success
    type: string
    sample: /etc/ssl/private/ansible.com.pem
 filename:
    description: Path to the generated TLS/SSL public key file
-    returned:
-        - changed
-        - success
+    returned: changed or success
    type: string
    sample: /etc/ssl/public/ansible.com.pem
 '''
--- a/lib/ansible/modules/database/proxysql/proxysql_mysql_users.py
+++ b/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": {
-        "changed": true,
-        "msg": "Added user to mysql_users",
-        "state": "present",
-        "user": {
-            "active": "1",
-            "backend": "1",
-            "default_hostgroup": "1",
-            "default_schema": null,
-            "fast_forward": "0",
-            "frontend": "1",
-            "max_connections": "10000",
-            "password": "VALUE_SPECIFIED_IN_NO_LOG_PARAMETER",
-            "schema_locked": "0",
-            "transaction_persistent": "0",
-            "use_ssl": "0",
-            "username": "guest_ro"
-        },
-        "username": "guest_ro"
-    }
+    sample:
+        changed: true
+        msg: Added user to mysql_users
+        state: present
+        user:
+            active: 1
+            backend: 1
+            default_hostgroup: 1
+            default_schema: null
+            fast_forward: 0
+            frontend: 1
+            max_connections: 10000
+            password: VALUE_SPECIFIED_IN_NO_LOG_PARAMETER
+            schema_locked: 0
+            transaction_persistent: 0
+            use_ssl: 0
+            username: guest_ro
+        username: guest_ro
 '''

 ANSIBLE_METADATA = {'metadata_version': '1.0',
--- a/lib/ansible/modules/files/archive.py
+++ b/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
--- a/lib/ansible/modules/files/find.py
+++ b/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",
--- a/lib/ansible/modules/files/stat.py
+++ b/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
--- a/lib/ansible/modules/monitoring/logicmonitor_facts.py
+++ b/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",
--- a/lib/ansible/modules/packaging/os/apt.py
+++ b/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
--- a/lib/ansible/modules/packaging/os/pacman.py
+++ b/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']
 '''

--- a/lib/ansible/modules/packaging/os/xbps.py
+++ b/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
 '''


--- a/lib/ansible/modules/remote_management/hpilo/hpilo_facts.py
+++ b/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
--- a/lib/ansible/modules/storage/netapp/netapp_e_facts.py
+++ b/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

--- a/lib/ansible/modules/storage/netapp/netapp_e_lun_mapping.py
+++ b/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: Mapping removed.
+msg:
+    description: Status of mapping
+    returned: always
+    type: string
+    sample: 'Mapping existing'
 '''
 import json

--- a/lib/ansible/modules/storage/netapp/netapp_e_snapshot_images.py
+++ b/lib/ansible/modules/storage/netapp/netapp_e_snapshot_images.py
@ -73,9 +73,16 @@ EXAMPLES = """
 """
 RETURN = """
 ---
-    changed: true
-    msg: "Created snapshot image"
-    image_id: "3400000060080E5000299B640063074057BC5C5E "
+    msg:
+        description: State of operation
+        type: string
+        returned: always
+        sample: "Created snapshot image"
+    image_id:
+        description: ID of snaphot image
+        type: string
+        returned: state == created
+        sample: "3400000060080E5000299B640063074057BC5C5E "
 """

 HEADERS = {
--- a/lib/ansible/modules/storage/netapp/netapp_e_storage_system.py
+++ b/lib/ansible/modules/storage/netapp/netapp_e_storage_system.py
@ -99,8 +99,11 @@ EXAMPLES = '''
 '''

 RETURN = '''
-msg: Storage system removed.
-msg: Storage system added.
+msg:
+    description: State of request
+    type: string
+    returned: always
+    sample: 'Storage system removed.'
 '''
 import json
 from datetime import datetime as dt, timedelta
--- a/lib/ansible/modules/storage/netapp/netapp_e_volume.py
+++ b/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: "Thin volume [workload_thin_vol] has been created."
-msg: "Volume [workload_vol_1] has been expanded."
-msg: "Volume [workload_vol_1] has been deleted."
-msg: "Volume [workload_vol_1] did not exist."
-msg: "Volume [workload_vol_1] already exists."
+msg:
+    description: State of volume
+    type: string
+    returned: always
+    sample: "Standard volume [workload_vol_1] has been created."
 '''

 import json
--- a/lib/ansible/modules/storage/netapp/sf_snapshot_schedule_manager.py
+++ b/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
--- a/lib/ansible/modules/system/aix_inittab.py
+++ b/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
 '''
--- a/lib/ansible/modules/system/authorized_key.py
+++ b/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.
--- a/lib/ansible/modules/system/parted.py
+++ b/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.
--- a/lib/ansible/modules/system/systemd.py
+++ b/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",
--- a/lib/ansible/modules/system/timezone.py
+++ b/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
--- a/lib/ansible/modules/utilities/logic/pause.py
+++ b/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
--- a/lib/ansible/modules/utilities/logic/wait_for_connection.py
+++ b/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
 '''
--- a/lib/ansible/modules/web_infrastructure/ansible_tower/tower_job_list.py
+++ b/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
--- a/lib/ansible/modules/web_infrastructure/ansible_tower/tower_job_wait.py
+++ b/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
--- a/lib/ansible/modules/web_infrastructure/letsencrypt.py
+++ b/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
--- a/lib/ansible/modules/windows/win_command.py
+++ b/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 ...']
 '''
--- a/lib/ansible/modules/windows/win_find.py
+++ b/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
--- a/lib/ansible/modules/windows/win_iis_webapppool.py
+++ b/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:
--- a/lib/ansible/modules/windows/win_regmerge.py
+++ b/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
--- a/lib/ansible/modules/windows/win_service.py
+++ b/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
 '''
--- a/lib/ansible/modules/windows/win_shell.py
+++ b/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 ...']
 '''
--- a/lib/ansible/modules/windows/win_stat.py
+++ b/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
--- a/lib/ansible/modules/windows/win_updates.py
+++ b/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:
--- a/lib/ansible/modules/windows/win_uri.py
+++ b/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