Improve module return values (#63541) (#63644)

* Remove lists from contains:, fix types, some more details.

* Adjust types.

* Add new type.

* Re-add meraki_mx_l7_firewall docs at right indentation level.

(cherry picked from commit a129499cf4)

lib/ansible/modules/cloud/alicloud/ali_instance.py

@@ -468,14 +468,14 @@ instances:
         security_groups:
             description: One or more security groups for the instance.
             returned: always
-            type: complex
+            type: list of complex
             contains:
-                - group_id:
+                group_id:
                     description: The ID of the security group.
                     returned: always
                     type: str
                     sample: sg-0123456
-                - group_name:
+                group_name:
                     description: The name of the security group.
                     returned: always
                     type: str

lib/ansible/modules/cloud/alicloud/ali_instance_info.py

@@ -309,14 +309,14 @@ instances:
         security_groups:
             description: One or more security groups for the instance.
             returned: always
-            type: complex
+            type: list of complex
             contains:
-                - group_id:
+                group_id:
                     description: The ID of the security group.
                     returned: always
                     type: str
                     sample: sg-0123456
-                - group_name:
+                group_name:
                     description: The name of the security group.
                     returned: always
                     type: str

lib/ansible/modules/cloud/amazon/aws_codebuild.py

@@ -257,11 +257,11 @@ project:
     cache:
       description: Cache settings for the build project.
       returned: when configured
-      type: complex
+      type: dict
     environment:
       description: Environment settings for the build
       returned: always
-      type: complex
+      type: dict
     service_role:
       description: IAM role to be used during build to access other AWS services.
       returned: always

lib/ansible/modules/cloud/amazon/aws_codecommit.py

@@ -71,7 +71,7 @@ repository_metadata:
     creation_date:
       description: "The date and time the repository was created, in timestamp format."
       returned: when state is present
-      type: datetime
+      type: str
       sample: "2018-10-16T13:21:41.261000+09:00"
     last_modified_date:
       description: "The date and time the repository was last modified, in timestamp format."
@@ -102,7 +102,7 @@ response_metadata:
     http_headers:
       description: "http headers of http response"
       returned: always
-      type: complex
+      type: dict
     http_status_code:
       description: "http status code of http response"
       returned: always

lib/ansible/modules/cloud/amazon/aws_secret.py

@@ -119,7 +119,7 @@ secret:
     version_ids_to_stages:
       description: Provide the secret version ids and the associated secret stage.
       returned: always
-      type: complex
+      type: dict
       sample: { "dc1ed59b-6d8e-4450-8b41-536dfe4600a9": [ "AWSCURRENT" ] }
 '''
 

lib/ansible/modules/cloud/amazon/ec2_instance.py

@@ -477,9 +477,9 @@ instances:
                 groups:
                     description: One or more security groups.
                     returned: always
-                    type: complex
+                    type: list of complex
                     contains:
-                        - group_id:
+                        group_id:
                             description: The ID of the security group.
                             returned: always
                             type: str
@@ -522,9 +522,9 @@ instances:
                 private_ip_addresses:
                     description: The private IPv4 addresses associated with the network interface.
                     returned: always
-                    type: complex
+                    type: list of complex
                     contains:
-                        - association:
+                        association:
                             description: The association information for an Elastic IP address (IPv4) associated with the network interface.
                             returned: always
                             type: complex
@@ -607,9 +607,9 @@ instances:
         product_codes:
             description: One or more product codes.
             returned: always
-            type: complex
+            type: list of complex
             contains:
-                - product_code_id:
+                product_code_id:
                     description: The product code.
                     returned: always
                     type: str
@@ -642,14 +642,14 @@ instances:
         security_groups:
             description: One or more security groups for the instance.
             returned: always
-            type: complex
+            type: list of complex
             contains:
-                - group_id:
+                group_id:
                     description: The ID of the security group.
                     returned: always
                     type: str
                     sample: sg-0123456
-                - group_name:
+                group_name:
                     description: The name of the security group.
                     returned: always
                     type: str

lib/ansible/modules/cloud/amazon/ec2_instance_info.py

@@ -263,9 +263,9 @@ instances:
                 groups:
                     description: One or more security groups.
                     returned: always
-                    type: complex
+                    type: list of complex
                     contains:
-                        - group_id:
+                        group_id:
                             description: The ID of the security group.
                             returned: always
                             type: str
@@ -308,9 +308,9 @@ instances:
                 private_ip_addresses:
                     description: The private IPv4 addresses associated with the network interface.
                     returned: always
-                    type: complex
+                    type: list of complex
                     contains:
-                        - association:
+                        association:
                             description: The association information for an Elastic IP address (IPv4) associated with the network interface.
                             returned: always
                             type: complex
@@ -393,9 +393,9 @@ instances:
         product_codes:
             description: One or more product codes.
             returned: always
-            type: complex
+            type: list of complex
             contains:
-                - product_code_id:
+                product_code_id:
                     description: The product code.
                     returned: always
                     type: str
@@ -428,14 +428,14 @@ instances:
         security_groups:
             description: One or more security groups for the instance.
             returned: always
-            type: complex
+            type: list of complex
             contains:
-                - group_id:
+                group_id:
                     description: The ID of the security group.
                     returned: always
                     type: str
                     sample: sg-0123456
-                - group_name:
+                group_name:
                     description: The name of the security group.
                     returned: always
                     type: str

lib/ansible/modules/cloud/amazon/ec2_vpc_nacl_info.py

@@ -89,14 +89,14 @@ nacls:
         ingress:
             description:
               - A list of NACL ingress rules with the following format.
-              - [rule no, protocol, allow/deny, v4 or v6 cidr, icmp_type, icmp_code, port from, port to]
+              - "C([rule no, protocol, allow/deny, v4 or v6 cidr, icmp_type, icmp_code, port from, port to])"
             returned: always
             type: list of list
             sample: [[100, 'tcp', 'allow', '0.0.0.0/0', null, null, 22, 22]]
         egress:
             description:
               - A list of NACL egress rules with the following format.
-              - [rule no, protocol, allow/deny, v4 or v6 cidr, icmp_type, icmp_code, port from, port to]
+              - "C([rule no, protocol, allow/deny, v4 or v6 cidr, icmp_type, icmp_code, port from, port to])"
             returned: always
             type: list of list
             sample: [[100, 'all', 'allow', '0.0.0.0/0', null, null, null, null]]

lib/ansible/modules/cloud/amazon/ec2_vpc_vpn_info.py

@@ -123,7 +123,7 @@ vpn_connections:
            last_status_change:
                description: The date and time of the last change in status.
                returned: always
-               type: datetime
+               type: str
                sample: "2018-02-09T14:35:27+00:00"
            outside_ip_address:
                description: The Internet-routable IP address of the virtual private gateway's outside interface.
@@ -140,6 +140,11 @@ vpn_connections:
                returned: always
                type: str
                sample: IPSEC IS DOWN
+           certificate_arn:
+               description: The Amazon Resource Name of the virtual private gateway tunnel endpoint certificate.
+               returned: when a private certificate is used for authentication
+               type: str
+               sample: "arn:aws:acm:us-east-1:123456789101:certificate/c544d8ce-20b8-4fff-98b0-example"
       vpn_connection_id:
         description: The ID of the VPN connection.
         returned: always

lib/ansible/modules/cloud/openstack/os_coe_cluster.py

@@ -105,7 +105,7 @@ cluster:
       created_at:
           description:
             - The time in UTC at which the cluster is created
-          type: datetime
+          type: str
           sample: "2018-08-16T10:29:45+00:00"
       create_timeout:
           description:

lib/ansible/modules/cloud/ovirt/ovirt_auth.py

@@ -169,7 +169,7 @@ ovirt_auth:
         ca_file:
             description: CA file, which is used to verify SSL/TLS connection.
             returned: success
-            type: path
+            type: str
             sample: "ca.pem"
         insecure:
             description: Flag indicating if insecure connection is used.

lib/ansible/modules/cloud/vmware/vcenter_folder.py

@@ -132,8 +132,12 @@ result:
     returned: On success
     type: complex
     contains:
-        path: the full path of the new folder
+        path:
-        msg: string stating about result
+            description: the full path of the new folder
+            type: str
+        msg:
+            description: string stating about result
+            type: str
 '''
 
 try:

lib/ansible/modules/files/stat.py

@@ -142,9 +142,9 @@ stat:
             type: str
             sample: '/path/to/file'
         mode:
-            description: Unix permissions of the file in octal
+            description: Unix permissions of the file in octal representation as a string
             returned: success, path exists and user can read stats
-            type: octal
+            type: str
             sample: 1755
         isdir:
             description: Tells you if the path is a directory

lib/ansible/modules/windows/win_updates.py

@@ -221,7 +221,7 @@ updates:
         id:
             description: Internal Windows Update GUID.
             returned: always
-            type: str (guid)
+            type: str
             sample: "fb95c1c8-de23-4089-ae29-fd3351d55421"
         installed:
             description: Was the update successfully installed.