Improve type documentation. (#62179) (#63142)

(cherry picked from commit a59b9d42693f8f86d86082820c14ef43c014d6a5)

10 files changed, 56 insertions, 7 deletions

diff --git a/lib/ansible/modules/cloud/docker/docker_compose.py b/lib/ansible/modules/cloud/docker/docker_compose.py
index a9c4488442..5e284cea87 100644
--- a/lib/ansible/modules/cloud/docker/docker_compose.py
+++ b/lib/ansible/modules/cloud/docker/docker_compose.py
@@ -47,6 +47,7 @@ options:
       - List of Compose file names relative to I(project_src). Overrides C(docker-compose.yml) or C(docker-compose.yaml).
       - Files are loaded and merged in the order given.
     type: list
+    elements: path
   state:
     description:
       - Desired state of the project.
@@ -64,6 +65,7 @@ options:
         on a subset of services.
       - If empty, which is the default, the operation will be performed on all services defined in the Compose file (or inline I(definition)).
     type: list
+    elements: str
   scale:
     description:
       - When I(state) is C(present) scale services. Provide a dictionary of key/value pairs where the key
diff --git a/lib/ansible/modules/cloud/docker/docker_container.py b/lib/ansible/modules/cloud/docker/docker_container.py
index 9f2ac3879c..2ac27317b9 100644
--- a/lib/ansible/modules/cloud/docker/docker_container.py
+++ b/lib/ansible/modules/cloud/docker/docker_container.py
@@ -50,10 +50,12 @@ options:
     description:
       - List of capabilities to add to the container.
     type: list
+    elements: str
   cap_drop:
     description:
       - List of capabilities to drop from the container.
     type: list
+    elements: str
     version_added: "2.7"
   cleanup:
     description:
@@ -119,10 +121,12 @@ options:
       - "List of host device bindings to add to the container. Each binding is a mapping expressed
         in the format: <path_on_host>:<path_in_container>:<cgroup_permissions>"
     type: list
+    elements: str
   device_read_bps:
     description:
       - "List of device path and read rate (bytes per second) from device."
     type: list
+    elements: dict
     suboptions:
       path:
         description:
@@ -142,6 +146,7 @@ options:
     description:
       - "List of device and write rate (bytes per second) to device."
     type: list
+    elements: dict
     suboptions:
       path:
         description:
@@ -161,6 +166,7 @@ options:
     description:
       - "List of device and read rate (IO per second) from device."
     type: list
+    elements: dict
     suboptions:
       path:
         description:
@@ -178,6 +184,7 @@ options:
     description:
       - "List of device and write rate (IO per second) to device."
     type: list
+    elements: dict
     suboptions:
       path:
         description:
@@ -195,14 +202,17 @@ options:
     description:
       - list of DNS options
     type: list
+    elements: str
   dns_servers:
     description:
       - List of custom DNS servers.
     type: list
+    elements: str
   dns_search_domains:
     description:
       - List of custom DNS search domains.
     type: list
+    elements: str
   domainname:
     description:
       - Container domainname.
@@ -223,6 +233,7 @@ options:
     description:
       - Command that overwrites the default ENTRYPOINT of the image.
     type: list
+    elements: str
   etc_hosts:
     description:
       - Dict of host-to-IP mappings, where each host name is a key in the dictionary.
@@ -235,6 +246,7 @@ options:
         If the port is already exposed using EXPOSE in a Dockerfile, it does not
         need to be exposed again.
     type: list
+    elements: str
     aliases:
       - exposed
       - expose
@@ -249,6 +261,7 @@ options:
     description:
       - List of additional group names and/or IDs that the container process will run as.
     type: list
+    elements: str
   healthcheck:
     description:
       - 'Configure a check that is run to determine whether or not containers for this service are "healthy".
@@ -343,6 +356,7 @@ options:
       - List of name aliases for linked containers in the format C(container_name:alias).
       - Setting this will force container to be restarted.
     type: list
+    elements: str
   log_driver:
     description:
       - Specify the logging driver. Docker uses I(json-file) by default.
@@ -389,6 +403,7 @@ options:
   mounts:
     version_added: "2.9"
     type: list
+    elements: dict
     description:
       - 'Specification for mounts to be added to the container. More powerful alternative to I(volumes).'
     suboptions:
@@ -490,6 +505,7 @@ options:
         network if C(networks) is specified. You need to explicitly use C(purge_networks) to enforce
         the removal of the default network (and all other networks not explicitly mentioned in C(networks)).
     type: list
+    elements: dict
     suboptions:
       name:
         description:
@@ -508,11 +524,13 @@ options:
         description:
           - A list of containers to link to.
         type: list
+        elements: str
       aliases:
         description:
           - List of aliases for this container in this network. These names
             can be used in the network to reach this container.
         type: list
+        elements: str
     version_added: "2.2"
   networks_cli_compatible:
     description:
@@ -590,6 +608,7 @@ options:
         Note that the first bridge network with a com.docker.network.bridge.host_binding_ipv4
         value encountered in the list of C(networks) is the one that will be used.
     type: list
+    elements: str
     aliases:
       - ports
   pull:
@@ -651,6 +670,7 @@ options:
     description:
       - List of security options in the form of C("label:user:User")
     type: list
+    elements: str
   state:
     description:
       - 'I(absent) - A container matching the specified name will be stopped and removed. Use force_kill to kill the container
@@ -703,6 +723,7 @@ options:
     description:
       - Mount a tmpfs directory
     type: list
+    elements: str
     version_added: 2.4
   tty:
     description:
@@ -713,6 +734,7 @@ options:
     description:
       - "List of ulimit options. A ulimit is specified as C(nofile:262144:262144)"
     type: list
+    elements: str
   sysctls:
     description:
       - Dictionary of key,value pairs.
@@ -739,6 +761,7 @@ options:
       - "Note that Ansible 2.7 and earlier only supported one mode, which had to be one of C(ro), C(rw),
         C(z), and C(Z)."
     type: list
+    elements: str
   volume_driver:
     description:
       - The container volume driver.
@@ -747,6 +770,7 @@ options:
     description:
       - List of container names or Ids to get volumes from.
     type: list
+    elements: str
   working_dir:
     description:
       - Path to the working directory.
diff --git a/lib/ansible/modules/cloud/docker/docker_image.py b/lib/ansible/modules/cloud/docker/docker_image.py
index 44449460d5..2b19ba6e49 100644
--- a/lib/ansible/modules/cloud/docker/docker_image.py
+++ b/lib/ansible/modules/cloud/docker/docker_image.py
@@ -57,6 +57,7 @@ options:
         description:
           - List of image names to consider as cache source.
         type: list
+        elements: str
       dockerfile:
         description:
           - Use with state C(present) and source C(build) to provide an alternate name for the Dockerfile to use when building an image.
diff --git a/lib/ansible/modules/cloud/docker/docker_image_info.py b/lib/ansible/modules/cloud/docker/docker_image_info.py
index 306213dbcd..7ffe47a0e5 100644
--- a/lib/ansible/modules/cloud/docker/docker_image_info.py
+++ b/lib/ansible/modules/cloud/docker/docker_image_info.py
@@ -38,6 +38,7 @@ options:
         where C(tag) is optional. If a tag is not provided, C(latest) will be used. Instead of image names, also
         image IDs can be used.
     type: list
+    elements: str
     required: yes
 
 extends_documentation_fragment:
diff --git a/lib/ansible/modules/cloud/docker/docker_network.py b/lib/ansible/modules/cloud/docker/docker_network.py
index b0601a2fd0..028d5758b5 100644
--- a/lib/ansible/modules/cloud/docker/docker_network.py
+++ b/lib/ansible/modules/cloud/docker/docker_network.py
@@ -32,6 +32,7 @@ options:
     description:
       - List of container names or container IDs to connect to a network.
     type: list
+    elements: str
     aliases:
       - containers
 
@@ -115,6 +116,7 @@ options:
         L(Docker docs,https://docs.docker.com/compose/compose-file/compose-file-v2/#ipam) for valid options and values.
         Note that I(iprange) is spelled differently here (we use the notation from the Docker SDK for Python).
     type: list
+    elements: dict
     suboptions:
       subnet:
         description:
diff --git a/lib/ansible/modules/cloud/docker/docker_node.py b/lib/ansible/modules/cloud/docker/docker_node.py
index 9ef36fb586..18c55d9b4e 100644
--- a/lib/ansible/modules/cloud/docker/docker_node.py
+++ b/lib/ansible/modules/cloud/docker/docker_node.py
@@ -59,6 +59,7 @@ options:
             - If I(labels_state) is C(replace) and I(labels) is not provided or empty then all labels assigned to
               node are removed and I(labels_to_remove) is ignored.
         type: list
+        elements: str
     availability:
         description: Node availability to assign. If not provided then node availability remains unchanged.
         choices:
diff --git a/lib/ansible/modules/cloud/docker/docker_node_info.py b/lib/ansible/modules/cloud/docker/docker_node_info.py
index a32545c2fd..b9094c9f16 100644
--- a/lib/ansible/modules/cloud/docker/docker_node_info.py
+++ b/lib/ansible/modules/cloud/docker/docker_node_info.py
@@ -33,6 +33,7 @@ options:
       - When identifying the node use either the hostname of the node (as registered in Swarm) or node ID.
       - If I(self) is C(true) then this parameter is ignored.
     type: list
+    elements: str
   self:
     description:
       - If C(true), queries the node (i.e. the docker daemon) the module communicates with.
diff --git a/lib/ansible/modules/cloud/docker/docker_stack.py b/lib/ansible/modules/cloud/docker/docker_stack.py
index 53cbc53fda..85fbd89aa4 100644
--- a/lib/ansible/modules/cloud/docker/docker_stack.py
+++ b/lib/ansible/modules/cloud/docker/docker_stack.py
@@ -41,6 +41,7 @@ options:
         referring to the path of the compose file on the target host
         or the YAML contents of a compose file nested as dictionary.
     type: list
+    # elements: raw
     default: []
   prune:
     description:
@@ -210,7 +211,7 @@ def main():
     module = AnsibleModule(
         argument_spec={
             'name': dict(type='str', required=True),
-            'compose': dict(type='list', default=[]),
+            'compose': dict(type='list', elements='raw', default=[]),
             'prune': dict(type='bool', default=False),
             'with_registry_auth': dict(type='bool', default=False),
             'resolve_image': dict(type='str', choices=['always', 'changed', 'never']),
diff --git a/lib/ansible/modules/cloud/docker/docker_swarm.py b/lib/ansible/modules/cloud/docker/docker_swarm.py
index c91212b5b4..c08e72af53 100644
--- a/lib/ansible/modules/cloud/docker/docker_swarm.py
+++ b/lib/ansible/modules/cloud/docker/docker_swarm.py
@@ -39,6 +39,7 @@ options:
         for idempotency checking.
       - Requires API version >= 1.39.
     type: list
+    elements: str
     version_added: "2.8"
   subnet_size:
     description:
@@ -98,6 +99,7 @@ options:
       - Remote address of one or more manager nodes of an existing Swarm to connect to.
       - Used with I(state=join).
     type: list
+    elements: str
   task_history_retention_limit:
     description:
       - Maximum number of tasks history stored.
diff --git a/lib/ansible/modules/cloud/docker/docker_swarm_service.py b/lib/ansible/modules/cloud/docker/docker_swarm_service.py
index aa1040aec3..f284fe0de4 100644
--- a/lib/ansible/modules/cloud/docker/docker_swarm_service.py
+++ b/lib/ansible/modules/cloud/docker/docker_swarm_service.py
@@ -26,6 +26,7 @@ options:
       - List arguments to be passed to the container.
       - Corresponds to the C(ARG) parameter of C(docker service create).
     type: list
+    elements: str
   command:
     description:
       - Command to execute when the container starts.
@@ -39,6 +40,7 @@ options:
       - Corresponds to the C(--config) option of C(docker service create).
       - Requires API version >= 1.30.
     type: list
+    elements: dict
     suboptions:
       config_id:
         description:
@@ -72,6 +74,7 @@ options:
       - Corresponds to the C(--constraint) option of C(docker service create).
       - Deprecated in 2.8, will be removed in 2.12. Use parameter C(placement.constraints) instead.
     type: list
+    elements: str
   container_labels:
     description:
       - Dictionary of key value pairs.
@@ -83,18 +86,21 @@ options:
       - Corresponds to the C(--dns) option of C(docker service create).
       - Requires API version >= 1.25.
     type: list
+    elements: str
   dns_search:
     description:
       - List of custom DNS search domains.
       - Corresponds to the C(--dns-search) option of C(docker service create).
       - Requires API version >= 1.25.
     type: list
+    elements: str
   dns_options:
     description:
       - List of custom DNS options.
       - Corresponds to the C(--dns-option) option of C(docker service create).
       - Requires API version >= 1.25.
     type: list
+    elements: str
   endpoint_mode:
     description:
       - Service endpoint mode.
@@ -120,6 +126,7 @@ options:
         variable that shows up more than once.
       - If variable also present in I(env), then I(env) value will override.
     type: list
+    elements: path
     version_added: "2.8"
   force_update:
     description:
@@ -134,6 +141,7 @@ options:
       - Corresponds to the C(--group) option of C(docker service update).
       - Requires API version >= 1.25.
     type: list
+    elements: str
     version_added: "2.8"
   healthcheck:
     description:
@@ -271,6 +279,7 @@ options:
       - List of dictionaries describing the service mounts.
       - Corresponds to the C(--mount) option of C(docker service create).
     type: list
+    elements: dict
     suboptions:
       source:
         description:
@@ -365,6 +374,7 @@ options:
         If changes are made the service will then be removed and recreated.
       - Corresponds to the C(--network) option of C(docker service create).
     type: list
+    elements: raw
   placement:
     description:
       - Configures service placement preferences and constraints.
@@ -374,12 +384,14 @@ options:
           - List of the service constraints.
           - Corresponds to the C(--constraint) option of C(docker service create).
         type: list
+        elements: str
       preferences:
         description:
           - List of the placement preferences as key value pairs.
           - Corresponds to the C(--placement-pref) option of C(docker service create).
           - Requires API version >= 1.27.
         type: list
+        elements: dict
     type: dict
     version_added: "2.8"
   publish:
@@ -388,6 +400,7 @@ options:
       - Corresponds to the C(--publish) option of C(docker service create).
       - Requires API version >= 1.25.
     type: list
+    elements: dict
     suboptions:
       published_port:
         description:
@@ -593,6 +606,7 @@ options:
       - Corresponds to the C(--secret) option of C(docker service create).
       - Requires API version >= 1.25.
     type: list
+    elements: dict
     suboptions:
       secret_id:
         description:
@@ -2673,14 +2687,14 @@ def main():
             mode=dict(type='str', choices=['ingress', 'host']),
         )),
         placement=dict(type='dict', options=dict(
-            constraints=dict(type='list'),
-            preferences=dict(type='list'),
+            constraints=dict(type='list', elements='str'),
+            preferences=dict(type='list', elements='dict'),
         )),
-        constraints=dict(type='list', removed_in_version='2.12'),
+        constraints=dict(type='list', elements='str', removed_in_version='2.12'),
         tty=dict(type='bool'),
-        dns=dict(type='list'),
-        dns_search=dict(type='list'),
-        dns_options=dict(type='list'),
+        dns=dict(type='list', elements='str'),
+        dns_search=dict(type='list', elements='str'),
+        dns_options=dict(type='list', elements='str'),
         healthcheck=dict(type='dict', options=dict(
             test=dict(type='raw'),
             interval=dict(type='str'),