Update return documentation - part2 (#193)

Update return documentation

It needs to be compatible with antsibull.

Author: PolonaM

plugins/modules/version_update.py

@@ -46,15 +46,39 @@
     - Version applied.
   returned: success
   type: dict
-  sample:
-    - uuid: 9.2.11.210763
-      description: 9.2.11 General Availability
-      change_log: ...Please allow between 20-40 minutes per node for the update to complete...
-      build_id: 210763
-      major_version: 9
-      minor_version: 2
-      revision: 11
-      timestamp: 0
+  contains:
+    uuid:
+      description: Unique identifier in format majorVersion.minorVersion.revision.buildID
+      type: str
+      sample: 9.2.11.210763
+    description:
+      description: Human-readable name for the update
+      type: str
+      sample: 9.2.11 General Availability
+    change_log:
+      description: Description of all changes that are in this update, in HTML format
+      type: str
+      sample: ...Please allow between 20-40 minutes per node for the update to complete...
+    build_id:
+      description: ID of the build which corresponds to this update
+      type: int
+      sample: 210763
+    major_version:
+      description: Major version number
+      type: int
+      sample: 9
+    minor_version:
+      description: Minor version number
+      type: int
+      sample: 2
+    revision:
+      description: Revision number
+      type: int
+      sample: 11
+    timestamp:
+      description: Unix timestamp when the update was released
+      type: int
+      sample: 0
 """
 
 from ansible.module_utils.basic import AnsibleModule

plugins/modules/version_update_status_info.py

@@ -37,15 +37,39 @@
     - None/null is returned if no update was ever applied.
   returned: success
   type: dict
-  sample:
-    - from_build: 207183
-      percent: 100
-      prepare_status: ""
-      update_status: COMPLETE
-      update_status_details: Update Complete. Press 'Reload' to reconnect
-      usernotes: ""
-      to_build: 209840
-      to_version: 9.1.18.209840
+  contains:
+    from_build:
+      description: Old build version
+      type: str
+      sample: 207183
+    percent:
+      description: Update progress in percentage
+      type: str
+      sample: 100
+    prepare_status:
+      description: Status of preparation necessary for update to start
+      type: str
+      sample: ""
+    update_status:
+      description: Update status
+      type: str
+      sample: COMPLETE
+    update_status_details:
+      description: Update status details
+      type: str
+      sample: Update Complete. Press 'Reload' to reconnect
+    usernotes:
+      description: Update status usernotes
+      type: str
+      sample: Update Complete. Press 'Reload' to reconnect
+    to_build:
+      description: New build version
+      type: str
+      sample: 209840
+    to_version:
+      description: New hypercore version
+      type: str
+      sample: 9.1.18.209840
 """
 
 from typing import Optional

plugins/modules/virtual_disk.py

@@ -63,12 +63,27 @@
     - Virtual disk record.
   returned: success
   type: dict
-  sample:
-    name: foobar.qcow2
-    uuid: 57ec1fba-506a-45b9-8950-ffc3dc102c6b
-    block_size: 1048576
-    size: 104857600
-    replication_factor: 2
+  contains:
+    block_size:
+      description: Size of individual blocks (the smallest unit of measurement for VSDs) on the drive, in bytes
+      type: int
+      sample: 1048576
+    name:
+      description: Name identifier
+      type: str
+      sample: demo-virtual-disk.qcow2
+    replication_factor:
+      description: How many copies of each block are stored on physical drives
+      type: int
+      sample: 2
+    size:
+      description: Total capacity, in bytes
+      type: int
+      sample: 1073741824
+    uuid:
+      description: Unique identifier
+      type: str
+      sample: 7983b298-c37a-4c99-8dfe-b2952e81b092
 """
 
 from ansible.module_utils.basic import AnsibleModule

plugins/modules/vm_snapshot_info.py

@@ -77,17 +77,48 @@
     - A list of VM Snapshot records.
   returned: success
   type: list
-  sample:
-    - automated_trigger_timestamp: 0
-      block_count_diff_from_serial_number: 2
-      label: snap-2
-      local_retain_until_timestamp: 0
-      remote_retain_until_timestamp: 0
-      replication: true
-      snapshot_uuid: 28d6ff95-2c31-4a1a-b3d9-47535164d6de
-      timestamp: 1679397326
-      type: USER
-      vm:
+  elements: dict
+  contains:
+    automated_trigger_timestamp:
+      description: Unix timestamp used when determining which automated snapshots to retain
+      type: int
+      sample: 0
+    block_count_diff_from_serial_number:
+      description: Snapshot serial number of the previous snapshot used to calculate VirDomainSnapshot.blockCountDiff
+      type: int
+      sample: 2
+    label:
+      description: User-readable label describing the snapshot
+      type: str
+      sample: snap-2
+    local_retain_until_timestamp:
+      description: Unix timestamp indicating when automated snapshots will be automatically removed
+      type: int
+      sample: 0
+    remote_retain_until_timestamp:
+      description: Unix timestamp indicating when remote automated snapshots will be removed
+      type: int
+      sample: 0
+    replication:
+      description: Will replicate snapshot to a remote system or not in case if replication is configured
+      type: bool
+      sample: true
+    snapshot_uuid:
+      description: Snapshot's unique identifier
+      type: str
+      sample: 28d6ff95-2c31-4a1a-b3d9-47535164d6de
+    timestamp:
+      description: Unix timestamp of when snapshot was created
+      type: int
+      sample: 1679397326
+    type:
+      description: Snapshot type
+      type: str
+      sample: USER
+    vm:
+      description: source VM
+      type: dict
+      sample:
         name: snapshot-test-vm-1
         snapshot_serial_number: 3
         uuid: 5e50977c-14ce-450c-8a1a-bf5c0afbcf43