[PR #11981/de42aec7 backport][stable-12] Improve module docs (#11986)

Improve module docs (#11981) * Fix _facts module documentation. * Get rid of some more 'type: complex'. (cherry picked from commit de42aec78b) Co-authored-by: Felix Fontein <felix@fontein.de>
2026-05-06 13:22:48 +00:00 · 2026-05-03 10:16:42 +00:00
parent c2c1899359
commit 82555713b7
25 changed files with 297 additions and 266 deletions
--- a/plugins/modules/ali_instance.py
+++ b/plugins/modules/ali_instance.py
@@ -344,7 +344,8 @@ RETURN = r"""
 instances:
  description: List of ECS instances.
  returned: always
-  type: complex
+  type: list
+  elements: dict
  contains:
    availability_zone:
      description: The availability zone of the instance is in.
--- a/plugins/modules/ali_instance_info.py
+++ b/plugins/modules/ali_instance_info.py
@@ -91,7 +91,8 @@ RETURN = r"""
 instances:
  description: List of ECS instances.
  returned: always
-  type: complex
+  type: list
+  elements: dict
  contains:
    availability_zone:
      description: The availability zone of the instance is in.
--- a/plugins/modules/cloud_init_data_facts.py
+++ b/plugins/modules/cloud_init_data_facts.py
@@ -43,45 +43,50 @@ EXAMPLES = r"""
 """

 RETURN = r"""
-cloud_init_data_facts:
-  description: Facts of result and status.
+ansible_facts:
+  description: The returned facts.
  returned: success
  type: dict
-  sample:
-    {
-      "status": {
-        "v1": {
-          "datasource": "DataSourceCloudStack",
-          "errors": []
+  contains:
+    cloud_init_data_facts:
+      description: Facts of result and status.
+      returned: success
+      type: dict
+      sample:
+        {
+          "status": {
+            "v1": {
+              "datasource": "DataSourceCloudStack",
+              "errors": []
+            }
+          },
+          "result": {
+            "v1": {
+              "datasource": "DataSourceCloudStack",
+              "init": {
+                "errors": [],
+                "finished": 1522066377.0185432,
+                "start": 1522066375.2648022
+              },
+              "init-local": {
+                "errors": [],
+                "finished": 1522066373.70919,
+                "start": 1522066373.4726632
+              },
+              "modules-config": {
+                "errors": [],
+                "finished": 1522066380.9097016,
+                "start": 1522066379.0011985
+              },
+              "modules-final": {
+                "errors": [],
+                "finished": 1522066383.56594,
+                "start": 1522066382.3449218
+              },
+              "stage": null
+            }
+          }
        }
-      },
-      "result": {
-        "v1": {
-          "datasource": "DataSourceCloudStack",
-          "init": {
-            "errors": [],
-            "finished": 1522066377.0185432,
-            "start": 1522066375.2648022
-          },
-          "init-local": {
-            "errors": [],
-            "finished": 1522066373.70919,
-            "start": 1522066373.4726632
-          },
-          "modules-config": {
-            "errors": [],
-            "finished": 1522066380.9097016,
-            "start": 1522066379.0011985
-          },
-          "modules-final": {
-            "errors": [],
-            "finished": 1522066383.56594,
-            "start": 1522066382.3449218
-          },
-          "stage": null
-        }
-      }
-    }
 """

 import os
--- a/plugins/modules/cloudflare_dns.py
+++ b/plugins/modules/cloudflare_dns.py
@@ -327,7 +327,7 @@ RETURN = r"""
 record:
  description: A dictionary containing the record data.
  returned: success, except on record deletion
-  type: complex
+  type: dict
  contains:
    comment:
      description: Comments or notes about the DNS record.
--- a/plugins/modules/facter_facts.py
+++ b/plugins/modules/facter_facts.py
@@ -48,12 +48,12 @@ EXAMPLES = r"""
 RETURN = r"""
 ansible_facts:
  description: Dictionary with one key C(facter).
-  returned: always
+  returned: success
  type: dict
  contains:
    facter:
      description: Dictionary containing facts discovered in the remote system.
-      returned: always
+      returned: success
      type: dict
 """

--- a/plugins/modules/hwc_evs_disk.py
+++ b/plugins/modules/hwc_evs_disk.py
@@ -223,7 +223,8 @@ snapshot_id:
 attachments:
  description:
    - Specifies the disk attachment information.
-  type: complex
+  type: list
+  elements: dict
  returned: success
  contains:
    attached_at:
--- a/plugins/modules/hwc_vpc_security_group.py
+++ b/plugins/modules/hwc_vpc_security_group.py
@@ -85,7 +85,8 @@ vpc_id:
 rules:
  description:
    - Specifies the security group rule, which ensures that resources in the security group can communicate with one another.
-  type: complex
+  type: list
+  elements: dict
  returned: success
  contains:
    description:
--- a/plugins/modules/ip2location_info.py
+++ b/plugins/modules/ip2location_info.py
@@ -48,59 +48,66 @@ EXAMPLES = r"""
 """

 RETURN = r"""
-record:
-  description: Dictionary of IP geolocation information for the IP address.
-  returned: changed
-  type: complex
-  contains:
-    ip:
-      description: "Public IP address of a host."
-      type: str
-      sample: "8.8.8.8"
-    country_code:
-      description: ISO 3166-1 alpha-2 country code.
-      type: str
-      sample: "US"
-    country_name:
-      description: Country name based on ISO 3166.
-      type: str
-      sample: "United States of America"
-    region_name:
-      description: State or province name.
-      type: str
-      sample: "California"
-    city_name:
-      description: City name.
-      type: str
-      sample: "Mountain View"
-    latitude:
-      description: Latitude of the city.
-      type: float
-      sample: 37.3860
-    longitude:
-      description: Longitude of the city.
-      type: float
-      sample: -122.0838
-    zip_code:
-      description: ZIP/Postal code.
-      type: str
-      sample: "94035"
-    time_zone:
-      description: UTC time zone (with DST supported).
-      type: str
-      sample: "-08:00"
-    asn:
-      description: Autonomous system number (ASN).
-      type: str
-      sample: "15169"
-    as:
-      description: Autonomous system (AS) name.
-      type: str
-      sample: "Google LLC"
-    is_proxy:
-      description: Whether is a proxy or not.
-      type: bool
-      sample: false
+ip:
+  description: "Public IP address of a host."
+  type: str
+  returned: success
+  sample: "8.8.8.8"
+country_code:
+  description: ISO 3166-1 alpha-2 country code.
+  type: str
+  returned: success
+  sample: "US"
+country_name:
+  description: Country name based on ISO 3166.
+  type: str
+  returned: success
+  sample: "United States of America"
+region_name:
+  description: State or province name.
+  type: str
+  returned: success
+  sample: "California"
+city_name:
+  description: City name.
+  type: str
+  returned: success
+  sample: "Mountain View"
+latitude:
+  description: Latitude of the city.
+  type: float
+  returned: success
+  sample: 37.3860
+longitude:
+  description: Longitude of the city.
+  type: float
+  returned: success
+  sample: -122.0838
+zip_code:
+  description: ZIP/Postal code.
+  type: str
+  returned: success
+  sample: "94035"
+time_zone:
+  description: UTC time zone (with DST supported).
+  type: str
+  returned: success
+  sample: "-08:00"
+asn:
+  description: Autonomous system number (ASN).
+  type: str
+  returned: success
+  sample: "15169"
+as:
+  description: Autonomous system (AS) name.
+  type: str
+  returned: success
+  sample: "Google LLC"
+is_proxy:
+  description: Whether is a proxy or not.
+  type: bool
+  returned: success
+  sample: false
 """

 import typing as t
--- a/plugins/modules/ipify_facts.py
+++ b/plugins/modules/ipify_facts.py
@@ -51,11 +51,16 @@ EXAMPLES = r"""
 """

 RETURN = r"""
-ipify_public_ip:
-  description: Public IP of the internet gateway.
+ansible_facts:
+  description: The returned facts.
  returned: success
-  type: str
-  sample: 1.2.3.4
+  type: dict
+  contains:
+    ipify_public_ip:
+      description: Public IP of the internet gateway.
+      returned: success
+      type: str
+      sample: 1.2.3.4
 """

 import json
--- a/plugins/modules/ipinfoio_facts.py
+++ b/plugins/modules/ipinfoio_facts.py
@@ -40,8 +40,8 @@ EXAMPLES = r"""
 RETURN = r"""
 ansible_facts:
  description: "Dictionary of IP geolocation facts for a host's IP address."
-  returned: changed
-  type: complex
+  returned: success
+  type: dict
  contains:
    ip:
      description: "Public IP address of a host."
--- a/plugins/modules/keycloak_authentication_required_actions.py
+++ b/plugins/modules/keycloak_authentication_required_actions.py
@@ -133,7 +133,7 @@ msg:
 end_state:
  description: Representation of the authentication required actions after module execution.
  returned: on success
-  type: complex
+  type: dict
  contains:
    alias:
      description:
--- a/plugins/modules/keycloak_authz_authorization_scope.py
+++ b/plugins/modules/keycloak_authz_authorization_scope.py
@@ -97,7 +97,7 @@ msg:
 end_state:
  description: Representation of the authorization scope after module execution.
  returned: on success
-  type: complex
+  type: dict
  contains:
    id:
      description: ID of the authorization scope.
--- a/plugins/modules/keycloak_authz_permission.py
+++ b/plugins/modules/keycloak_authz_permission.py
@@ -161,7 +161,7 @@ msg:
 end_state:
  description: Representation of the authorization permission after module execution.
  returned: on success
-  type: complex
+  type: dict
  contains:
    id:
      description: ID of the authorization permission.
--- a/plugins/modules/keycloak_authz_permission_info.py
+++ b/plugins/modules/keycloak_authz_permission_info.py
@@ -76,7 +76,7 @@ msg:
 queried_state:
  description: State of the resource (a policy) as seen by Keycloak.
  returned: on success
-  type: complex
+  type: dict
  contains:
    id:
      description: ID of the authorization permission.
--- a/plugins/modules/keycloak_clientsecret_regenerate.py
+++ b/plugins/modules/keycloak_clientsecret_regenerate.py
@@ -115,7 +115,7 @@ msg:
 end_state:
  description: Representation of the client credential after module execution.
  returned: on success
-  type: complex
+  type: dict
  contains:
    type:
      description: Credential type.
--- a/plugins/modules/keycloak_group.py
+++ b/plugins/modules/keycloak_group.py
@@ -250,7 +250,7 @@ msg:
 end_state:
  description: Representation of the group after module execution (sample is truncated).
  returned: on success
-  type: complex
+  type: dict
  contains:
    id:
      description: GUID that identifies the group.
--- a/plugins/modules/listen_ports_facts.py
+++ b/plugins/modules/listen_ports_facts.py
@@ -78,13 +78,14 @@ EXAMPLES = r"""
 RETURN = r"""
 ansible_facts:
  description: Dictionary containing details of TCP and UDP ports with listening servers.
-  returned: always
-  type: complex
+  returned: success
+  type: dict
  contains:
    tcp_listen:
      description: A list of processes that are listening on a TCP port.
-      returned: if TCP servers were found
+      returned: success
      type: list
+      elements: dict
      contains:
        address:
          description: The address the server is listening on.
@@ -135,8 +136,9 @@ ansible_facts:
          sample: "mysql"
    udp_listen:
      description: A list of processes that are listening on a UDP port.
-      returned: if UDP servers were found
+      returned: success
      type: list
+      elements: dict
      contains:
        address:
          description: The address the server is listening on.
--- a/plugins/modules/nosh.py
+++ b/plugins/modules/nosh.py
@@ -141,7 +141,7 @@ status:
  description: A dictionary with the key=value pairs returned by C(system-control show-json) or V(none) if the service is
    not loaded.
  returned: success
-  type: complex
+  type: dict
  contains:
    After:
      description: []        # FIXME
--- a/plugins/modules/omapi_host.py
+++ b/plugins/modules/omapi_host.py
@@ -104,7 +104,7 @@ RETURN = r"""
 lease:
  description: Dictionary containing host information.
  returned: success
-  type: complex
+  type: dict
  contains:
    ip-address:
      description: IP address, if there is.
--- a/plugins/modules/one_image_info.py
+++ b/plugins/modules/one_image_info.py
@@ -78,7 +78,8 @@ EXAMPLES = r"""
 RETURN = r"""
 images:
  description: A list of images info.
-  type: complex
+  type: list
+  elements: dict
  returned: success
  contains:
    id:
--- a/plugins/modules/one_vm.py
+++ b/plugins/modules/one_vm.py
@@ -449,7 +449,8 @@ instances_ids:
  sample: [1234, 1235]
 instances:
  description: A list of instances info whose state is changed or which are fetched with O(instance_ids) option.
-  type: complex
+  type: list
+  elements: dict
  returned: success
  contains:
    vm_id:
@@ -563,7 +564,8 @@ tagged_instances:
  description:
    - A list of instances info based on a specific attributes and/or labels that are specified with O(count_attributes) and
      O(count_labels) options.
-  type: complex
+  type: list
+  elements: dict
  returned: success
  contains:
    vm_id:
--- a/plugins/modules/parted.py
+++ b/plugins/modules/parted.py
@@ -135,45 +135,43 @@ notes:
 """

 RETURN = r"""
-partition_info:
-  description: Current partition information.
+disk:
+  description: Generic device information.
+  type: dict
  returned: success
-  type: complex
-  contains:
-    disk:
-      description: Generic device information.
-      type: dict
-    partitions:
-      description: List of device partitions.
-      type: list
-    script:
-      description: Parted script executed by module.
-      type: str
  sample:
-    "disk":
-      "dev": "/dev/sdb"
-      "logical_block": 512
-      "model": "VMware Virtual disk"
-      "physical_block": 512
-      "size": 5.0
-      "table": "msdos"
-      "unit": "GiB"
-    "partitions":
-      - "begin": 0.0
-        "end": 1.0
-        "flags": ["boot", "lvm"]
-        "fstype": ""
-        "name": ""
-        "num": 1
-        "size": 1.0
-      - "begin": 1.0
-        "end": 5.0
-        "flags": []
-        "fstype": ""
-        "name": ""
-        "num": 2
-        "size": 4.0
-    "script": "unit KiB print "
+    "dev": "/dev/sdb"
+    "logical_block": 512
+    "model": "VMware Virtual disk"
+    "physical_block": 512
+    "size": 5.0
+    "table": "msdos"
+    "unit": "GiB"
+partitions:
+  description: List of device partitions.
+  type: list
+  elements: dict
+  returned: success
+  sample:
+    - "begin": 0.0
+      "end": 1.0
+      "flags": ["boot", "lvm"]
+      "fstype": ""
+      "name": ""
+      "num": 1
+      "size": 1.0
+    - "begin": 1.0
+      "end": 5.0
+      "flags": []
+      "fstype": ""
+      "name": ""
+      "num": 2
+      "size": 4.0
+script:
+  description: Parted script executed by module.
+  type: str
+  returned: success
+  sample: "unit KiB print "
 """

 EXAMPLES = r"""
--- a/plugins/modules/usb_facts.py
+++ b/plugins/modules/usb_facts.py
@@ -36,33 +36,33 @@ EXAMPLES = r"""
 RETURN = r"""
 ansible_facts:
  description: Dictionary containing details of connected USB devices.
-  returned: always
+  returned: success
  type: dict
  contains:
    usb_devices:
      description: A list of USB devices available.
-      returned: always
+      returned: success
      type: list
      elements: dict
      contains:
        bus:
          description: The bus the usb device is connected to.
-          returned: always
+          returned: success
          type: str
          sample: "001"
        device:
          description: The device number occupied on the bus.
-          returned: always
+          returned: success
          type: str
          sample: "002"
        id:
          description: ID of the USB device.
-          returned: always
+          returned: success
          type: str
          sample: "1d6b:0002"
        name:
          description: Human readable name of the device.
-          returned: always
+          returned: success
          type: str
          sample: Linux Foundation 2.0 root hub
 """
--- a/plugins/modules/zfs_facts.py
+++ b/plugins/modules/zfs_facts.py
@@ -73,7 +73,7 @@ EXAMPLES = r"""
 RETURN = r"""
 name:
  description: ZFS dataset name.
-  returned: always
+  returned: success
  type: str
  sample: rpool/var/spool
 parsable:
@@ -86,67 +86,73 @@ recurse:
  returned: if O(recurse=True)
  type: bool
  sample: true
-zfs_datasets:
-  description: ZFS dataset facts.
-  returned: always
-  type: str
-  sample:
-    "aclinherit": "restricted"
-    "aclmode": "discard"
-    "atime": "on"
-    "available": "43.8G"
-    "canmount": "on"
-    "casesensitivity": "sensitive"
-    "checksum": "on"
-    "compression": "off"
-    "compressratio": "1.00x"
-    "copies": "1"
-    "creation": "Thu Jun 16 11:37 2016"
-    "dedup": "off"
-    "devices": "on"
-    "exec": "on"
-    "filesystem_count": "none"
-    "filesystem_limit": "none"
-    "logbias": "latency"
-    "logicalreferenced": "18.5K"
-    "logicalused": "3.45G"
-    "mlslabel": "none"
-    "mounted": "yes"
-    "mountpoint": "/rpool"
-    "name": "rpool"
-    "nbmand": "off"
-    "normalization": "none"
-    "org.openindiana.caiman:install": "ready"
-    "primarycache": "all"
-    "quota": "none"
-    "readonly": "off"
-    "recordsize": "128K"
-    "redundant_metadata": "all"
-    "refcompressratio": "1.00x"
-    "referenced": "29.5K"
-    "refquota": "none"
-    "refreservation": "none"
-    "reservation": "none"
-    "secondarycache": "all"
-    "setuid": "on"
-    "sharenfs": "off"
-    "sharesmb": "off"
-    "snapdir": "hidden"
-    "snapshot_count": "none"
-    "snapshot_limit": "none"
-    "sync": "standard"
-    "type": "filesystem"
-    "used": "4.41G"
-    "usedbychildren": "4.41G"
-    "usedbydataset": "29.5K"
-    "usedbyrefreservation": "0"
-    "usedbysnapshots": "0"
-    "utf8only": "off"
-    "version": "5"
-    "vscan": "off"
-    "written": "29.5K"
-    "xattr": "on"
-    "zoned": "off"
+ansible_facts:
+  description: Dictionary containing all the detailed information about the ZFS facts.
+  returned: success
+  type: dict
+  contains:
+    zfs_datasets:
+      description: ZFS dataset facts.
+      returned: always
+      type: list
+      elements: dict
+      sample:
+        - "aclinherit": "restricted"
+          "aclmode": "discard"
+          "atime": "on"
+          "available": "43.8G"
+          "canmount": "on"
+          "casesensitivity": "sensitive"
+          "checksum": "on"
+          "compression": "off"
+          "compressratio": "1.00x"
+          "copies": "1"
+          "creation": "Thu Jun 16 11:37 2016"
+          "dedup": "off"
+          "devices": "on"
+          "exec": "on"
+          "filesystem_count": "none"
+          "filesystem_limit": "none"
+          "logbias": "latency"
+          "logicalreferenced": "18.5K"
+          "logicalused": "3.45G"
+          "mlslabel": "none"
+          "mounted": "yes"
+          "mountpoint": "/rpool"
+          "name": "rpool"
+          "nbmand": "off"
+          "normalization": "none"
+          "org.openindiana.caiman:install": "ready"
+          "primarycache": "all"
+          "quota": "none"
+          "readonly": "off"
+          "recordsize": "128K"
+          "redundant_metadata": "all"
+          "refcompressratio": "1.00x"
+          "referenced": "29.5K"
+          "refquota": "none"
+          "refreservation": "none"
+          "reservation": "none"
+          "secondarycache": "all"
+          "setuid": "on"
+          "sharenfs": "off"
+          "sharesmb": "off"
+          "snapdir": "hidden"
+          "snapshot_count": "none"
+          "snapshot_limit": "none"
+          "sync": "standard"
+          "type": "filesystem"
+          "used": "4.41G"
+          "usedbychildren": "4.41G"
+          "usedbydataset": "29.5K"
+          "usedbyrefreservation": "0"
+          "usedbysnapshots": "0"
+          "utf8only": "off"
+          "version": "5"
+          "vscan": "off"
+          "written": "29.5K"
+          "xattr": "on"
+          "zoned": "off"
 """

 from collections import defaultdict
--- a/plugins/modules/zpool_facts.py
+++ b/plugins/modules/zpool_facts.py
@@ -51,56 +51,57 @@ EXAMPLES = r"""
 RETURN = r"""
 ansible_facts:
  description: Dictionary containing all the detailed information about the ZFS pool facts.
-  returned: always
-  type: complex
+  returned: success
+  type: dict
  contains:
    ansible_zfs_pools:
      description: ZFS pool facts.
-      returned: always
-      type: str
+      returned: success
+      type: list
+      elements: dict
      sample:
-        "allocated": "3.46G"
-        "altroot": "-"
-        "autoexpand": "off"
-        "autoreplace": "off"
-        "bootfs": "rpool/ROOT/openindiana"
-        "cachefile": "-"
-        "capacity": "6%"
-        "comment": "-"
-        "dedupditto": "0"
-        "dedupratio": "1.00x"
-        "delegation": "on"
-        "expandsize": "-"
-        "failmode": "wait"
-        "feature@async_destroy": "enabled"
-        "feature@bookmarks": "enabled"
-        "feature@edonr": "enabled"
-        "feature@embedded_data": "active"
-        "feature@empty_bpobj": "active"
-        "feature@enabled_txg": "active"
-        "feature@extensible_dataset": "enabled"
-        "feature@filesystem_limits": "enabled"
-        "feature@hole_birth": "active"
-        "feature@large_blocks": "enabled"
-        "feature@lz4_compress": "active"
-        "feature@multi_vdev_crash_dump": "enabled"
-        "feature@sha512": "enabled"
-        "feature@skein": "enabled"
-        "feature@spacemap_histogram": "active"
-        "fragmentation": "3%"
-        "free": "46.3G"
-        "freeing": "0"
-        "guid": "15729052870819522408"
-        "health": "ONLINE"
-        "leaked": "0"
-        "listsnapshots": "off"
-        "name": "rpool"
-        "readonly": "off"
-        "size": "49.8G"
-        "version": "-"
+        - "allocated": "3.46G"
+          "altroot": "-"
+          "autoexpand": "off"
+          "autoreplace": "off"
+          "bootfs": "rpool/ROOT/openindiana"
+          "cachefile": "-"
+          "capacity": "6%"
+          "comment": "-"
+          "dedupditto": "0"
+          "dedupratio": "1.00x"
+          "delegation": "on"
+          "expandsize": "-"
+          "failmode": "wait"
+          "feature@async_destroy": "enabled"
+          "feature@bookmarks": "enabled"
+          "feature@edonr": "enabled"
+          "feature@embedded_data": "active"
+          "feature@empty_bpobj": "active"
+          "feature@enabled_txg": "active"
+          "feature@extensible_dataset": "enabled"
+          "feature@filesystem_limits": "enabled"
+          "feature@hole_birth": "active"
+          "feature@large_blocks": "enabled"
+          "feature@lz4_compress": "active"
+          "feature@multi_vdev_crash_dump": "enabled"
+          "feature@sha512": "enabled"
+          "feature@skein": "enabled"
+          "feature@spacemap_histogram": "active"
+          "fragmentation": "3%"
+          "free": "46.3G"
+          "freeing": "0"
+          "guid": "15729052870819522408"
+          "health": "ONLINE"
+          "leaked": "0"
+          "listsnapshots": "off"
+          "name": "rpool"
+          "readonly": "off"
+          "size": "49.8G"
+          "version": "-"
 name:
  description: ZFS pool name.
-  returned: always
+  returned: success
  type: str
  sample: rpool
 parsable: