Updated return documentation for v1.2.0

Author: PolonaM

plugins/modules/api.py

@@ -163,19 +163,16 @@
 
 
 RETURN = r"""
-records:
+record:
   description:
-    - In case of I(action=get), the records from the specified endpoint. Below is example output for I(action=get).
-    - In case of I(action=post), I(action=patch) or I(action=delete), the task tag, returned from the HyperCore API.
+    - In case of I(action=get), list of records from the specified endpoint. Exact content depend on called API endpoint.
+    - In case of I(action=post), I(action=patch) or I(action=delete), usually the task tag dictionary, returned from the HyperCore API.
+      If task tag is returned, the module internally waits on returned task tag to be finished.
   returned: success
-  type: list
+  type: dict
   sample:
-    - uuid: 81178af9-fb4c-4e98-9dba-d272adc2cae2
-      virDomainUUID: 17a23be5-9cf2-4d79-b02f-b2a0cb29a0f7
-      type: RTL8139
-      macAddress: 7C:4C:58:18:23:4F
-      connected: true
-      ipv4Addresses: []
+    createdUUID: 51e6d073-7566-4273-9196-58720117bd7f
+    taskTag: 359
 """
 
 

plugins/modules/certificate.py

@@ -48,12 +48,15 @@
     - Certificate record.
   returned: success
   type: dict
-  sample:
-    certificate:|
-      -----BEGIN CERTIFICATE-----
-      MIIGKzCCBBOgAwIBAgIUWaGzXfgSUuwwPJu3F2Q/Ru/O8JQwDQYJKoZIhvcNAQEL
-      ...
-      -----END CERTIFICATE-----
+  contains:
+    certificate:
+      description: Cluster SSL certificate
+      type: str
+      sample:
+        -----BEGIN CERTIFICATE-----
+        MIIGKzCCBBOgAwIBAgIUWaGzXfgSUuwwPJu3F2Q/Ru/O8JQwDQYJKoZIhvcNAQEL
+        ...
+        -----END CERTIFICATE-----
 """
 
 from ansible.module_utils.basic import AnsibleModule

plugins/modules/cluster_name.py

@@ -45,10 +45,19 @@
     - Updated cluster name.
   returned: success
   type: dict
-  sample:
-    - icos_version: 9.2.11.210763
-      name: updated_cluster_name
-      uuid: a5d9148c-37f7-4b43-843c-196751d3c050
+  contains:
+    icos_version:
+      description: HyperCore ICOS version
+      type: str
+      sample: 9.2.11.210763
+    name:
+      description: Cluster name
+      type: str
+      sample: PUB4
+    uuid:
+      description: Cluster UUID
+      type: str
+      sample: a5d9148c-37f7-4b43-843c-196751d3c050
 """
 
 from ansible.module_utils.basic import AnsibleModule

plugins/modules/dns_config.py

@@ -77,27 +77,39 @@
     - Output from modifying entries of the DNS configuration on HyperCore API.
   returned: success
   type: dict
-  sample:
-    uuid: "dnsconfig_guid"
+  contains:
+    uuid:
+      description: Unique identifer
+      type: str
+      sample: dnsconfig_guid
     server_ips:
-      - "1.1.1.1"
-      - "1.0.0.1"
-    search_domains: []
+      description: IP address or hostname of DNS servers
+      type: list
+      elements: str
+      sample: 1.1.1.1
+    search_domains:
+      description: Domain search list used to resolve fully qualified domain names
+      type: list
+      elements: str
+      sample: example.domain1.com
     latest_task_tag:
-      completed: 1673966351
-      created: 1673966345
-      descriptionParameters: []
-      formattedDescription: "DNSConfig Update"
-      formattedMessage: ""
-      messageParameters: []
-      modified: 1673966351
-      nodeUUIDs:
-        - "32c5012d-7d7b-49b4-9201-70e02b0d8758"
-      objectUUID: "dnsconfig_guid"
-      progressPercent: 100
-      sessionID: "b8c45c35-3349-49e0-9474-0edfa73a2162"
-      state: "COMPLETE"
-      taskTag: "396"
+      description: Latest Task Tag
+      type: dict
+      sample:
+        completed: 1673946776
+        created: 1673946770
+        descriptionParameters: []
+        formattedDescription: "DNSConfig Update"
+        formattedMessage: ""
+        messageParameters: []
+        modified: 1673946776
+        nodeUUIDs:
+          - "32c5012d-7d7b-49b4-9201-70e02b0d8758"
+        objectUUID: "dnsconfig_guid"
+        progressPercent: 100
+        sessionID: "775155cc-bc4e-445c-9efa-a304f4f66c82"
+        state: "COMPLETE"
+        taskTag: "359"
 """
 
 

plugins/modules/dns_config_info.py

@@ -37,27 +37,39 @@
     - DNS configuration record.
   returned: success
   type: dict
-  sample:
-    uuid: "dnsconfig_guid"
+  contains:
+    uuid:
+      description: Unique identifer
+      type: str
+      sample: dnsconfig_guid
     server_ips:
-      - "1.1.1.1"
-      - "1.0.0.1"
-    search_domains: []
+      description: IP address or hostname of DNS servers
+      type: list
+      elements: str
+      sample: 1.1.1.1
+    search_domains:
+      description: Domain search list used to resolve fully qualified domain names
+      type: list
+      elements: str
+      sample: example.domain1.com
     latest_task_tag:
-      completed: 1673946776
-      created: 1673946770
-      descriptionParameters: []
-      formattedDescription: "DNSConfig Update"
-      formattedMessage: ""
-      messageParameters: []
-      modified: 1673946776
-      nodeUUIDs:
-        - "32c5012d-7d7b-49b4-9201-70e02b0d8758"
-      objectUUID: "dnsconfig_guid"
-      progressPercent: 100
-      sessionID: "775155cc-bc4e-445c-9efa-a304f4f66c82"
-      state: "COMPLETE"
-      taskTag: "359"
+      description: Latest Task Tag
+      type: dict
+      sample:
+        completed: 1673946776
+        created: 1673946770
+        descriptionParameters: []
+        formattedDescription: "DNSConfig Update"
+        formattedMessage: ""
+        messageParameters: []
+        modified: 1673946776
+        nodeUUIDs:
+          - "32c5012d-7d7b-49b4-9201-70e02b0d8758"
+        objectUUID: "dnsconfig_guid"
+        progressPercent: 100
+        sessionID: "775155cc-bc4e-445c-9efa-a304f4f66c82"
+        state: "COMPLETE"
+        taskTag: "359"
 """
 
 

plugins/modules/email_alert.py

@@ -79,26 +79,44 @@
     - Output from modifying entries of the Email Alert Recipients on HyperCore API.
   returned: success
   type: dict
-  sample:
-    alert_tag_uuid: 0
-    email: sample@sample.com
+  contains:
+    alert_tag_uuid:
+      description: Unique identifier for an AlertTag
+      type: str
+      sample: 0
+    email:
+      description: Email address of the alert recipient
+      type: str
+      sample: sample@sample.com
     latest_task_tag:
-      completed: 1675680830
-      created: 1675680830
-      descriptionParameters: []
-      formattedDescription: Create Alert Email Target
-      formattedMessage: ""
-      messageParameters: []
-      modified: 1675680830
-      nodeUUIDs: []
-      objectUUID: 8664ed18-c354-4bab-be96-78dae5f6377f
-      progressPercent: 100
-      sessionID: 2bed8c34-1ef3-4366-8895-360f4f786afe
-      state: COMPLETE
-      taskTag: 813
-    resend_delay: 86400
-    silent_period: 900
-    uuid: 8664ed18-c354-4bab-be96-78dae5f6377f
+      description: Latest Task Tag
+      type: dict
+      sample:
+        completed: 1675680830
+        created: 1675680830
+        descriptionParameters: []
+        formattedDescription: Create Alert Email Target
+        formattedMessage: ""
+        messageParameters: []
+        modified: 1675680830
+        nodeUUIDs: []
+        objectUUID: 8664ed18-c354-4bab-be96-78dae5f6377f
+        progressPercent: 100
+        sessionID: 2bed8c34-1ef3-4366-8895-360f4f786afe
+        state: COMPLETE
+        taskTag: 813
+    resend_delay:
+      description: Alert resend delay in seconds
+      type: int
+      sample: 86400
+    silent_period:
+      description: Alerts will not resend if there are additional event triggers within this time in seconds
+      type: int
+      sample: 900
+    uuid:
+      description: Unique identifer
+      type: str
+      sample: default-target
 """
 
 

plugins/modules/email_alert_info.py

@@ -37,10 +37,19 @@
     - A list of Email Alert Recipient records.
   returned: success
   type: list
-  sample:
-    - alert_tag_uuid: 0
-      email: sample@sample.com
-      latest_task_tag:
+  contains:
+    alert_tag_uuid:
+      description: Unique identifier for an AlertTag
+      type: str
+      sample: 0
+    email:
+      description: Email address of the alert recipient
+      type: str
+      sample: sample@sample.com
+    latest_task_tag:
+      description: Latest Task Tag
+      type: dict
+      sample:
         completed: 1675680830
         created: 1675680830
         descriptionParameters: []
@@ -54,9 +63,18 @@
         sessionID: 2bed8c34-1ef3-4366-8895-360f4f786afe
         state: COMPLETE
         taskTag: 813
-      resend_delay: 86400
-      silent_period: 900
-      uuid: 8664ed18-c354-4bab-be96-78dae5f6377f
+    resend_delay:
+      description: Alert resend delay in seconds
+      type: int
+      sample: 86400
+    silent_period:
+      description: Alerts will not resend if there are additional event triggers within this time in seconds
+      type: int
+      sample: 900
+    uuid:
+      description: Unique identifer
+      type: str
+      sample: default-target
 """
 
 

plugins/modules/iso_info.py

@@ -53,12 +53,37 @@
     - If I(name) is not specified, all ISO images will be returned
   returned: success
   type: list
-  sample:
-    - mounts: []
-      name: SW_DVD9_Win_Server_STD_CORE_2022_2108.11_64Bit_English_DC_STD_MLF_X23-17134.ISO
-      ready_for_insert: true
-      size: 5110759424
-      uuid: 51e6d073-7566-4273-9196-58720117bd7f
+  elements: dict
+  contains:
+    mounts:
+      description: VMs this image is attached to
+      type: list
+      elements: dict
+      sample:
+        vm_uuid: 51e6d073-7566-4273-9196-58720117bd7f
+        vm_name: xlab
+    name:
+      description: Filename of the image
+      type: str
+      sample: SW_DVD9_Win_Server_STD_CORE_2022_2108.11_64Bit_English_DC_STD_MLF_X23-17134.ISO
+    path:
+      description: Storage device used in conjunction with VirDomainBlockDevice.path
+      type: str
+      sample: scribe/171afce9-2452-4294-9bc4-6e8ae49f7e4c
+    ready_for_insert:
+      description:
+        - The flag indicates the ISO image content is fully uploaded, and image is ready to be used.
+        - Flag is `false` only for images that are in middle of upload, or where upload was terminated in middle.
+      type: bool
+      sample: true
+    size:
+      description: Size of the ISO file, in bytes
+      type: int
+      sample: 5110759424
+    uuid:
+      description: Unique identifier
+      type: str
+      sample: 171afce9-2452-4294-9bc4-6e8ae49f7e4c
 """
 
 

plugins/modules/node_info.py

@@ -35,11 +35,24 @@
     - A list of node records.
   returned: success
   type: list
-  sample:
-    - node_uuid: "51e6d073-7566-4273-9196-58720117bd7f"
-      backplane_ip: "10.0.0.1"
-      lan_ip: "10.0.0.1"
-      peer_id: 1
+  elements: dict
+  contains:
+    node_uuid:
+      description: Unique identifier
+      type: str
+      sample: 51e6d073-7566-4273-9196-58720117bd7f
+    backplane_ip:
+      description: IP address on the backplane network
+      type: str
+      sample: 10.0.0.1
+    lan_ip:
+      description: IP address on the LAN network
+      type: str
+      sample: 10.0.0.2
+    peer_id:
+      description: Cluster map peer identifier
+      type: str
+      sample: 1
 """
 
 from ansible.module_utils.basic import AnsibleModule

plugins/modules/oidc_config.py

@@ -66,10 +66,19 @@
     - OIDC config record.
   returned: success
   type: dict
-  sample:
-    client_id: 12345
-    config_url: https://login.microsoftonline.com/your_uuid/v2.0/.well-known/openid-configuration
-    scopes: "openid+profile"
+  contains:
+    client_id:
+      description: Provided by authentication server when configuring a new client
+      type: str
+      sample: d2298ec0-0596-49d2-9554-840a2fe20603
+    config_url:
+      description: The OpenID Connect Provider Configuration Information endpoint
+      type: str
+      sample: https://login.microsoftonline.com/your_uuid/v2.0/.well-known/openid-configuration
+    scopes:
+      description: Scopes required to obtain necessary claims
+      type: str
+      sample: openid+profile
 """
 
 from ansible.module_utils.basic import AnsibleModule