Repository: ansible-collections/amazon.aws

Issue:
aws_ec2 inventory example doesn't match documented type for hostnames
### Summary

For [aws_ec2 inventory](https://ansible-collections.github.io/amazon.aws/branch/main/collections/amazon/aws/aws_ec2_inventory.html#ansible-collections-amazon-aws-aws-ec2-inventory), the documentation for `hostnames` says "list / elements=dictionary" with key `name` being required.

But in the example there's a list of `union[dictionary|str]`:

```
hostnames:
  - tag:Name=Tag1,Name=Tag2  # Return specific hosts only
  - tag:CustomDNSName
  - dns-name
  - name: 'tag:Name=Tag1,Name=Tag2'
  - name: 'private-ip-address'
    separator: '_'
    prefix: 'tag:Name'
  - name: 'test_literal' # Using literal values for hostname
    separator: '-'       # Hostname will be aws-test_literal
    prefix: 'aws'
```

At a glance, it looks like the example should not work, because it doesn't match the `hostnames` docs.
In particular, since these strings contain colons, will Ansible interpret this as `{"tag": "CustomDNSName"}`?

If the module allows type types of list members, one string, one dict, the documentation should say so.



### Issue Type

Documentation Report

### Component Name

aws_ec2 inventory

### Ansible Version

N/A

### Collection Versions

N/A

### Configuration

N/A

### OS / Environment

N/A

### Additional Information

_No response_

### Code of Conduct

- [X] I agree to follow the Ansible Code of Conduct


Discussion:

Resolving patch:
diff --git a/plugins/inventory/aws_ec2.py b/plugins/inventory/aws_ec2.py
--- a/plugins/inventory/aws_ec2.py
+++ b/plugins/inventory/aws_ec2.py
@@ -32,16 +32,17 @@
   hostnames:
     description:
       - A list in order of precedence for hostname variables.
+      - The elements of the list can be a dict with the keys mentioned below or a string.
+      - Can be one of the options specified in U(http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options).
+      - If value provided does not exist in the above options, it will be used as a literal string.
+      - To use tags as hostnames use the syntax tag:Name=Value to use the hostname Name_Value, or tag:Name to use the value of the Name tag.
     type: list
-    elements: dict
+    elements: raw
     default: []
     suboptions:
       name:
         description:
           - Name of the host.
-          - Can be one of the options specified in U(http://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html#options).
-          - To use tags as hostnames use the syntax tag:Name=Value to use the hostname Name_Value, or tag:Name to use the value of the Name tag.
-          - If value provided does not exist in the above options, it will be used as a literal string.
         type: str
         required: True
       prefix:
@@ -773,6 +774,9 @@ def parse(self, inventory, loader, path, cache=True):
         use_contrib_script_compatible_ec2_tag_keys = self.get_option("use_contrib_script_compatible_ec2_tag_keys")
         use_ssm_inventory = self.get_option("use_ssm_inventory")
 
+        if not all(isinstance(element, (dict, str)) for element in hostnames):
+            self.fail_aws("Hostnames should be a list of dict and str.")
+
         if self.get_option("include_extra_api_calls"):
             self.display.deprecate(
                 "The include_extra_api_calls option has been deprecated and will be removed in release 6.0.0.",


Test patch: