From c57679cd48a80a7d0ffae05ad91d7c2202355f75 Mon Sep 17 00:00:00 2001
From: Mandar Kulkarni <mandar242@gmail.com>
Date: Tue, 11 Jun 2024 19:17:20 -0700
Subject: [PATCH 01/12] update return block - s3_bucket_info

---
 plugins/modules/s3_bucket_info.py | 188 +++++++++++++++++++++---------
 1 file changed, 134 insertions(+), 54 deletions(-)

diff --git a/plugins/modules/s3_bucket_info.py b/plugins/modules/s3_bucket_info.py
index b382e5eebd3..1c21716e3fa 100644
--- a/plugins/modules/s3_bucket_info.py
+++ b/plugins/modules/s3_bucket_info.py
@@ -164,16 +164,24 @@
 """
 
 RETURN = r"""
-bucket_list:
-  description: "List of buckets"
+buckets:
+  description: A list of S3 buckets.
   returned: always
   type: complex
   contains:
+    bucket_accelerate_configuration:
+      description: The accelerate configuration of the bucket.
+      returned: when O(bucket_facts=true) and O(bucket_accelerate_configuration=true).
+      type: dict
+      sample: {
+                'Status': 'Enabled',
+                'RequestCharged': 'requester'
+              }
     name:
       description: Bucket name.
       returned: always
       type: str
-      sample: a-testing-bucket-name
+      sample: "a-testing-bucket-name"
     creation_date:
       description: Bucket creation date timestamp.
       returned: always
@@ -181,8 +189,16 @@
       sample: "2021-01-21T12:44:10+00:00"
     public_access_block:
       description: Bucket public access block configuration.
-      returned: when I(bucket_facts=true) and I(public_access_block=true)
+      returned: when O(bucket_facts=true) and O(public_access_block=true)
       type: complex
+      sample: {
+                "PublicAccessBlockConfiguration": {
+                    "BlockPublicAcls": true,
+                    "BlockPublicPolicy": true,
+                    "IgnorePublicAcls": true,
+                    "RestrictPublicBuckets": true
+                }
+              }
       contains:
         PublicAccessBlockConfiguration:
           description: PublicAccessBlockConfiguration data.
@@ -192,107 +208,161 @@
             BlockPublicAcls:
               description: BlockPublicAcls setting value.
               type: bool
-              sample: true
             BlockPublicPolicy:
               description: BlockPublicPolicy setting value.
               type: bool
-              sample: true
             IgnorePublicAcls:
               description: IgnorePublicAcls setting value.
               type: bool
-              sample: true
             RestrictPublicBuckets:
               description: RestrictPublicBuckets setting value.
               type: bool
-              sample: true
     bucket_name_filter:
       description: String used to limit buckets. See I(name_filter).
-      returned: when I(name_filter) is defined
+      returned: when O(name_filter) is defined
       type: str
-      sample: filter-by-this-string
+      sample: "filter-by-this-string"
     bucket_acl:
       description: Bucket ACL configuration.
-      returned: when I(bucket_facts=true) and I(bucket_acl=true)
+      returned: when O(bucket_facts=true) and O(bucket_acl=true).
       type: complex
       contains:
         Grants:
           description: List of ACL grants.
           type: list
-          sample: []
+          elements: dict
+          sample: [
+                    {
+                        "Grantee": {
+                            "DisplayName": "abc-aws-root+721234567890",
+                            "ID": "1234567890cbc0f1234567890f1234567890c123456789012123456789091234",
+                            "Type": "CanonicalUser"
+                        },
+                        "Permission": "FULL_CONTROL"
+                    }
+                  ]
+          contains:
+            Grantee:
+              description: The person being granted permissions.
+              type: dict
+              contains:
+                DisplayName:
+                  description: Screen name of the grantee.
+                  type: str
+                ID:
+                  description: The canonical user ID of the grantee.
+                  type: str
+                Type:
+                  description: Type of grantee.
+                  type: str
+        Permission:
+          description: Specifies the permission given to the grantee.
+          type: str
         Owner:
           description: Bucket owner information.
           type: complex
+          sample: {
+                    "DisplayName": "abc-aws-root+721234567890",
+                    "ID": "1234567890cbc0f1234567890f1234567890c123456789012123456789091234"
+                  }
           contains:
             DisplayName:
               description: Bucket owner user display name.
-              returned: always
               type: str
-              sample: username
             ID:
               description: Bucket owner user ID.
-              returned: always
               type: str
-              sample: 123894e509349etc
     bucket_cors:
       description: Bucket CORS configuration.
-      returned: when I(bucket_facts=true) and I(bucket_cors=true)
+      returned: when O(bucket_facts=true) and O(bucket_cors=true)
       type: complex
       contains:
         CORSRules:
           description: Bucket CORS configuration.
-          returned: when CORS rules are defined for the bucket
+          returned: When CORS rules are defined for the bucket
           type: list
           sample: []
     bucket_encryption:
       description: Bucket encryption configuration.
-      returned: when I(bucket_facts=true) and I(bucket_encryption=true)
+      returned: when O(bucket_facts=true) and O(bucket_encryption=true).
       type: complex
+      sample: {
+                "ServerSideEncryptionConfiguration": {
+                    "Rules": [
+                        {
+                          "ApplyServerSideEncryptionByDefault": {
+                              "SSEAlgorithm": "AES256"
+                          },
+                          "BucketKeyEnabled": true
+                        }
+                    ]
+                  }
+                }
       contains:
         ServerSideEncryptionConfiguration:
           description: ServerSideEncryptionConfiguration configuration.
-          returned: when encryption is enabled on the bucket
+          returned: when encryption is enabled on the bucket.
           type: complex
           contains:
             Rules:
               description: List of applied encryptio rules.
-              returned: when encryption is enabled on the bucket
+              returned: when encryption is enabled on the bucket.
               type: list
-              sample: { "ApplyServerSideEncryptionByDefault": { "SSEAlgorithm": "AES256" }, "BucketKeyEnabled": False }
+              elements: dict
+              contains:
+                ApplyServerSideEncryptionByDefault:
+                  description: Specifies the default server-side encryption to apply to new objects in the bucket.
+                  type: dict
+                  contains:
+                    SSEAlgorithm:
+                      description: Server-side encryption algorithm to use for the default encryption.
+                      type: str
+                    KMSMasterKeyID:
+                      description: Amazon Web Services Key Management Service (KMS) customer Amazon Web Services KMS key ID to use for the default encryption.
+                      type: str
+                BucketKeyEnabled:
+                  description: Specifies whether Amazon S3 should use an S3 Bucket Key with server-side encryption using KMS (SSE-KMS) for new objects in the bucket.
+                  type: bool
     bucket_lifecycle_configuration:
       description: Bucket lifecycle configuration settings.
-      returned: when I(bucket_facts=true) and I(bucket_lifecycle_configuration=true)
+      returned: when O(bucket_facts=true) and O(bucket_lifecycle_configuration=true).
       type: complex
       contains:
         Rules:
           description: List of lifecycle management rules.
-          returned: when lifecycle configuration is present
+          returned: when lifecycle configuration is present.
           type: list
-          sample: [{ "Status": "Enabled", "ID": "example-rule" }]
+          sample: [
+                    {
+                      "Status": "Enabled",
+                      "ID": "example-rule"
+                    }
+                  ]
     bucket_location:
       description: Bucket location.
-      returned: when I(bucket_facts=true) and I(bucket_location=true)
+      returned: when O(bucket_facts=true) and O(bucket_location=true).
       type: complex
       contains:
         LocationConstraint:
           description: AWS region.
           returned: always
           type: str
-          sample: us-east-2
+          sample: "us-east-2"
     bucket_logging:
       description: Server access logging configuration.
-      returned: when I(bucket_facts=true) and I(bucket_logging=true)
+      returned: when O(bucket_facts=true) and O(bucket_logging=true).
       type: complex
       contains:
         LoggingEnabled:
           description: Server access logging configuration.
-          returned: when server access logging is defined for the bucket
+          returned: when server access logging is defined for the bucket.
           type: complex
           contains:
             TargetBucket:
               description: Target bucket name.
               returned: always
               type: str
-              sample: logging-bucket-name
+              sample: "logging-bucket-name"
             TargetPrefix:
               description: Prefix in target bucket.
               returned: always
@@ -300,117 +370,127 @@
               sample: ""
     bucket_notification_configuration:
       description: Bucket notification settings.
-      returned: when I(bucket_facts=true) and I(bucket_notification_configuration=true)
+      returned: when O(bucket_facts=true) and O(bucket_notification_configuration=true).
       type: complex
       contains:
         TopicConfigurations:
           description: List of notification events configurations.
-          returned: when at least one notification is configured
+          returned: when at least one notification is configured.
           type: list
           sample: []
     bucket_ownership_controls:
       description: Preffered object ownership settings.
-      returned: when I(bucket_facts=true) and I(bucket_ownership_controls=true)
+      returned: when O(bucket_facts=true) and O(bucket_ownership_controls=true)
       type: complex
+      sample: {
+                "OwnershipControls": {
+                  "Rules": [
+                      {
+                        "ObjectOwnership": "BucketOwnerEnforced"
+                      }
+                  ]
+                }
+              }
       contains:
         OwnershipControls:
           description: Object ownership settings.
-          returned: when ownership controls are defined for the bucket
+          returned: when ownership controls are defined for the bucket.
           type: complex
           contains:
             Rules:
               description: List of ownership rules.
-              returned: when ownership rule is defined
+              returned: when ownership rule is defined.
               type: list
-              sample: [{ "ObjectOwnership:": "ObjectWriter" }]
     bucket_policy:
       description: Bucket policy contents.
-      returned: when I(bucket_facts=true) and I(bucket_policy=true)
+      returned: when O(bucket_facts=true) and O(bucket_policy=true).
       type: str
       sample: '{"Version":"2012-10-17","Statement":[{"Sid":"AddCannedAcl","Effect":"Allow",..}}]}'
     bucket_policy_status:
       description: Status of bucket policy.
-      returned: when I(bucket_facts=true) and I(bucket_policy_status=true)
+      returned: when O(bucket_facts=true) and O(bucket_policy_status=true).
       type: complex
       contains:
         PolicyStatus:
           description: Status of bucket policy.
-          returned: when bucket policy is present
+          returned: when bucket policy is present.
           type: complex
           contains:
             IsPublic:
               description: Report bucket policy public status.
-              returned: when bucket policy is present
+              returned: when bucket policy is present.
               type: bool
               sample: True
     bucket_replication:
       description: Replication configuration settings.
-      returned: when I(bucket_facts=true) and I(bucket_replication=true)
+      returned: when O(bucket_facts=true) and O(bucket_replication=true).
       type: complex
       contains:
         Role:
           description: IAM role used for replication.
-          returned: when replication rule is defined
+          returned: when replication rule is defined.
           type: str
           sample: "arn:aws:iam::123:role/example-role"
         Rules:
           description: List of replication rules.
-          returned: when replication rule is defined
+          returned: when replication rule is defined/
           type: list
           sample: [{ "ID": "rule-1", "Filter": "{}" }]
     bucket_request_payment:
       description: Requester pays setting.
-      returned: when I(bucket_facts=true) and I(bucket_request_payment=true)
+      returned: when O(bucket_facts=true) and O(bucket_request_payment=true)
       type: complex
+      sample: {
+                "Payer": "BucketOwner"
+              }
       contains:
         Payer:
           description: Current payer.
           returned: always
           type: str
-          sample: BucketOwner
     bucket_tagging:
       description: Bucket tags.
-      returned: when I(bucket_facts=true) and I(bucket_tagging=true)
+      returned: when O(bucket_facts=true) and O(bucket_tagging=true).
       type: dict
       sample: { "Tag1": "Value1", "Tag2": "Value2" }
     bucket_website:
       description: Static website hosting.
-      returned: when I(bucket_facts=true) and I(bucket_website=true)
+      returned: when O(bucket_facts=true) and O(bucket_website=true).
       type: complex
       contains:
         ErrorDocument:
           description: Object serving as HTTP error page.
-          returned: when static website hosting is enabled
+          returned: when static website hosting is enabled.
           type: dict
           sample: { "Key": "error.html" }
         IndexDocument:
           description: Object serving as HTTP index page.
-          returned: when static website hosting is enabled
+          returned: when static website hosting is enabled.
           type: dict
           sample: { "Suffix": "error.html" }
         RedirectAllRequestsTo:
           description: Website redict settings.
-          returned: when redirect requests is configured
+          returned: when redirect requests is configured.
           type: complex
           contains:
             HostName:
               description: Hostname to redirect.
               returned: always
               type: str
-              sample: www.example.com
+              sample: "www.example.com"
             Protocol:
               description: Protocol used for redirect.
               returned: always
               type: str
-              sample: https
+              sample: "https"
     bucket_versioning:
       description:
         - The versioning state of the bucket.
         - This will also specify whether MFA delete is enabled in the bucket versioning configuration.
           if only the bucket has been configured with MFA delete.
-      returned: when I(bucket_facts=true) and I(bucket_versioning=true)
+      returned: when O(bucket_facts=true) and O(bucket_versioning=true).
       type: dict
-      sample: { 'Status': 'Enabled' }
+      sample: { "Status": "Enabled" }
       version_added: 7.2.0
 """
 

From 4de1c549c8a307b05cda0de90499acf8af3ef383 Mon Sep 17 00:00:00 2001
From: Mandar Kulkarni <mandar242@gmail.com>
Date: Wed, 12 Jun 2024 16:15:27 -0700
Subject: [PATCH 02/12] update return block - s3_bucket

---
 plugins/modules/s3_bucket.py | 65 +++++++++++++++++++++++++-----------
 1 file changed, 45 insertions(+), 20 deletions(-)

diff --git a/plugins/modules/s3_bucket.py b/plugins/modules/s3_bucket.py
index d259286f9c0..da631e3dc69 100644
--- a/plugins/modules/s3_bucket.py
+++ b/plugins/modules/s3_bucket.py
@@ -290,25 +290,26 @@
 
 RETURN = r"""
 encryption:
-    description:
-        - Server-side encryption of the objects in the S3 bucket.
-    type: str
-    returned: I(state=present)
-    sample: ''
+    description: Server-side encryption of the objects in the S3 bucket.
+    type: dict
+    returned: when O(state=present)
+    sample: {
+            "SSEAlgorithm": "AES256"
+            }
 name:
-    description: Name of the S3 bucket.
+    description: Bucket name.
+    returned: when O(state=present)
     type: str
-    returned: I(state=present)
-    sample: "2d3ce10a8210d36d6b4d23b822892074complex"
+    sample: "a-testing-bucket-name"
 object_ownership:
     description: S3 bucket's ownership controls.
     type: str
-    returned: I(state=present)
+    returned: when O(state=present)
     sample: "BucketOwnerPreferred"
 policy:
     description: S3 bucket's policy.
     type: dict
-    returned: I(state=present)
+    returned: when O(state=present)
     sample: {
         "Statement": [
             {
@@ -322,15 +323,14 @@
         "Version": "2012-10-17"
     }
 requester_pays:
-    description:
-        - Indicates that the requester was successfully charged for the request.
-    type: str
-    returned: I(state=present)
-    sample: ''
+    description: Indicates that the requester was successfully charged for the request.
+    type: bool
+    returned: when O(state=present)
+    sample: true
 tags:
     description: S3 bucket's tags.
     type: dict
-    returned: I(state=present)
+    returned: when O(state=present)
     sample: {
         "Tag1": "tag1",
         "Tag2": "tag2"
@@ -338,16 +338,41 @@
 versioning:
     description: S3 bucket's versioning configuration.
     type: dict
-    returned: I(state=present)
+    returned: when O(state=present)
     sample: {
         "MfaDelete": "Disabled",
         "Versioning": "Enabled"
     }
+    contains:
+        MfaDelete:
+            description: Specifies whether MFA delete is enabled in the bucket versioning configuration.
+            returned: when O(state=presnet) and MfaDelete configured on bucket.
+            type: str
+        Versioning:
+            description: The versioning state of the bucket.
+            type: str
 acl:
     description: S3 bucket's canned ACL.
     type: dict
-    returned: I(state=present)
-    sample: 'public-read'
+    returned: when O(state=present).
+    sample: "public-read"
+object_lock_enabled:
+    description: Whether S3 Object Lock to be enabled.
+    type: bool
+    returned: when O(state=present)
+    sample: false
+public_access_block:
+    description: Bucket public access block configuration.
+    returned: when O(state=present)
+    type: complex
+    sample: {
+                "PublicAccessBlockConfiguration": {
+                    "BlockPublicAcls": true,
+                    "BlockPublicPolicy": true,
+                    "IgnorePublicAcls": true,
+                    "RestrictPublicBuckets": true
+                }
+            }
 """
 
 import json
@@ -469,7 +494,7 @@ def handle_bucket_requester_pays(s3_client, module: AnsibleAWSModule, name: str)
                     put_bucket_request_payment(s3_client, name, payer)
                     requester_pays_status = wait_payer_is_applied(module, s3_client, name, payer, should_fail=True)
                 requester_pays_changed = True
-
+    import q; q(requester_pays_status, "+++=+++++++++")
     return requester_pays_changed, requester_pays
 
 

From 7422fb2fffe6f2abbb305188df7cc3fe1d6ab69b Mon Sep 17 00:00:00 2001
From: Mandar Kulkarni <mandar242@gmail.com>
Date: Wed, 12 Jun 2024 16:31:37 -0700
Subject: [PATCH 03/12] sanity fixes s3_bucket

---
 plugins/modules/s3_bucket.py      | 18 +++++++++++++++++-
 plugins/modules/s3_bucket_info.py |  3 ++-
 2 files changed, 19 insertions(+), 2 deletions(-)

diff --git a/plugins/modules/s3_bucket.py b/plugins/modules/s3_bucket.py
index da631e3dc69..0452f163288 100644
--- a/plugins/modules/s3_bucket.py
+++ b/plugins/modules/s3_bucket.py
@@ -373,6 +373,23 @@
                     "RestrictPublicBuckets": true
                 }
             }
+    contains:
+        PublicAccessBlockConfiguration:
+            description: The PublicAccessBlock configuration currently in effect for this Amazon S3 bucket.
+            type: dict
+            contains:
+                BlockPublicAcls:
+                    description: Specifies whether Amazon S3 should block public access control lists (ACLs) for this bucket and objects in this bucket.
+                    type: bool
+                BlockPublicPolicy:
+                    description: Specifies whether Amazon S3 should block public bucket policies for this bucket.
+                    type: bool
+                IgnorePublicAcls:
+                    description: Specifies whether Amazon S3 should ignore public ACLs for this bucket and objects in this bucket.
+                    type: bool
+                RestrictPublicBuckets:
+                    description: Specifies whether Amazon S3 should restrict public bucket policies for this bucket.
+                    type: bool
 """
 
 import json
@@ -494,7 +511,6 @@ def handle_bucket_requester_pays(s3_client, module: AnsibleAWSModule, name: str)
                     put_bucket_request_payment(s3_client, name, payer)
                     requester_pays_status = wait_payer_is_applied(module, s3_client, name, payer, should_fail=True)
                 requester_pays_changed = True
-    import q; q(requester_pays_status, "+++=+++++++++")
     return requester_pays_changed, requester_pays
 
 
diff --git a/plugins/modules/s3_bucket_info.py b/plugins/modules/s3_bucket_info.py
index 1c21716e3fa..39c24a75549 100644
--- a/plugins/modules/s3_bucket_info.py
+++ b/plugins/modules/s3_bucket_info.py
@@ -321,7 +321,8 @@
                       description: Amazon Web Services Key Management Service (KMS) customer Amazon Web Services KMS key ID to use for the default encryption.
                       type: str
                 BucketKeyEnabled:
-                  description: Specifies whether Amazon S3 should use an S3 Bucket Key with server-side encryption using KMS (SSE-KMS) for new objects in the bucket.
+                  description:
+                    - Specifies whether Amazon S3 should use an S3 Bucket Key with server-side encryption using KMS (SSE-KMS) for new objects in the bucket.
                   type: bool
     bucket_lifecycle_configuration:
       description: Bucket lifecycle configuration settings.

From 1a81124bfd64a6dd04383f66d89a6614ff7fff6f Mon Sep 17 00:00:00 2001
From: Mandar Kulkarni <mandar242@gmail.com>
Date: Wed, 12 Jun 2024 16:43:12 -0700
Subject: [PATCH 04/12] sanity fixes s3_bucket_info

---
 plugins/modules/s3_bucket_info.py | 34 +++++++++++++++----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/plugins/modules/s3_bucket_info.py b/plugins/modules/s3_bucket_info.py
index 39c24a75549..47f5be43256 100644
--- a/plugins/modules/s3_bucket_info.py
+++ b/plugins/modules/s3_bucket_info.py
@@ -171,7 +171,7 @@
   contains:
     bucket_accelerate_configuration:
       description: The accelerate configuration of the bucket.
-      returned: when O(bucket_facts=true) and O(bucket_accelerate_configuration=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_accelerate_configuration=true).
       type: dict
       sample: {
                 'Status': 'Enabled',
@@ -189,7 +189,7 @@
       sample: "2021-01-21T12:44:10+00:00"
     public_access_block:
       description: Bucket public access block configuration.
-      returned: when O(bucket_facts=true) and O(public_access_block=true)
+      returned: when O(bucket_facts=true) and  RV(buckets.public_access_block=true)
       type: complex
       sample: {
                 "PublicAccessBlockConfiguration": {
@@ -224,7 +224,7 @@
       sample: "filter-by-this-string"
     bucket_acl:
       description: Bucket ACL configuration.
-      returned: when O(bucket_facts=true) and O(bucket_acl=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_acl=true).
       type: complex
       contains:
         Grants:
@@ -274,7 +274,7 @@
               type: str
     bucket_cors:
       description: Bucket CORS configuration.
-      returned: when O(bucket_facts=true) and O(bucket_cors=true)
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_cors=true)
       type: complex
       contains:
         CORSRules:
@@ -284,7 +284,7 @@
           sample: []
     bucket_encryption:
       description: Bucket encryption configuration.
-      returned: when O(bucket_facts=true) and O(bucket_encryption=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_encryption=true).
       type: complex
       sample: {
                 "ServerSideEncryptionConfiguration": {
@@ -326,7 +326,7 @@
                   type: bool
     bucket_lifecycle_configuration:
       description: Bucket lifecycle configuration settings.
-      returned: when O(bucket_facts=true) and O(bucket_lifecycle_configuration=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_lifecycle_configuration=true).
       type: complex
       contains:
         Rules:
@@ -341,7 +341,7 @@
                   ]
     bucket_location:
       description: Bucket location.
-      returned: when O(bucket_facts=true) and O(bucket_location=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_location=true).
       type: complex
       contains:
         LocationConstraint:
@@ -351,7 +351,7 @@
           sample: "us-east-2"
     bucket_logging:
       description: Server access logging configuration.
-      returned: when O(bucket_facts=true) and O(bucket_logging=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_logging=true).
       type: complex
       contains:
         LoggingEnabled:
@@ -371,7 +371,7 @@
               sample: ""
     bucket_notification_configuration:
       description: Bucket notification settings.
-      returned: when O(bucket_facts=true) and O(bucket_notification_configuration=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_notification_configuration=true).
       type: complex
       contains:
         TopicConfigurations:
@@ -381,7 +381,7 @@
           sample: []
     bucket_ownership_controls:
       description: Preffered object ownership settings.
-      returned: when O(bucket_facts=true) and O(bucket_ownership_controls=true)
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_ownership_controls=true)
       type: complex
       sample: {
                 "OwnershipControls": {
@@ -404,12 +404,12 @@
               type: list
     bucket_policy:
       description: Bucket policy contents.
-      returned: when O(bucket_facts=true) and O(bucket_policy=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_policy=true).
       type: str
       sample: '{"Version":"2012-10-17","Statement":[{"Sid":"AddCannedAcl","Effect":"Allow",..}}]}'
     bucket_policy_status:
       description: Status of bucket policy.
-      returned: when O(bucket_facts=true) and O(bucket_policy_status=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_policy_status=true).
       type: complex
       contains:
         PolicyStatus:
@@ -424,7 +424,7 @@
               sample: True
     bucket_replication:
       description: Replication configuration settings.
-      returned: when O(bucket_facts=true) and O(bucket_replication=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_replication=true).
       type: complex
       contains:
         Role:
@@ -439,7 +439,7 @@
           sample: [{ "ID": "rule-1", "Filter": "{}" }]
     bucket_request_payment:
       description: Requester pays setting.
-      returned: when O(bucket_facts=true) and O(bucket_request_payment=true)
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_request_payment=true)
       type: complex
       sample: {
                 "Payer": "BucketOwner"
@@ -451,12 +451,12 @@
           type: str
     bucket_tagging:
       description: Bucket tags.
-      returned: when O(bucket_facts=true) and O(bucket_tagging=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_tagging=true).
       type: dict
       sample: { "Tag1": "Value1", "Tag2": "Value2" }
     bucket_website:
       description: Static website hosting.
-      returned: when O(bucket_facts=true) and O(bucket_website=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_website=true).
       type: complex
       contains:
         ErrorDocument:
@@ -489,7 +489,7 @@
         - The versioning state of the bucket.
         - This will also specify whether MFA delete is enabled in the bucket versioning configuration.
           if only the bucket has been configured with MFA delete.
-      returned: when O(bucket_facts=true) and O(bucket_versioning=true).
+      returned: when O(bucket_facts=true) and RV(buckets.bucket_versioning=true).
       type: dict
       sample: { "Status": "Enabled" }
       version_added: 7.2.0

From 2abcda5c57cb84e9745b18b1f74501fcd5ec5b93 Mon Sep 17 00:00:00 2001
From: Mandar Kulkarni <mandar242@gmail.com>
Date: Thu, 13 Jun 2024 13:35:12 -0700
Subject: [PATCH 05/12] update return block - s3_object

---
 plugins/modules/s3_object.py | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/plugins/modules/s3_object.py b/plugins/modules/s3_object.py
index c3e45004a37..e08903b7ddd 100644
--- a/plugins/modules/s3_object.py
+++ b/plugins/modules/s3_object.py
@@ -377,12 +377,12 @@
   description: Message indicating the status of the operation.
   returned: always
   type: str
-  sample: PUT operation complete
+  sample: "PUT operation complete"
 url:
   description: URL of the object.
   returned: (for put and geturl operations)
   type: str
-  sample: https://my-bucket.s3.amazonaws.com/my-key.txt?AWSAccessKeyId=<access-key>&Expires=1506888865&Signature=<signature>
+  sample: "https://my-bucket.s3.amazonaws.com/my-key.txt?AWSAccessKeyId=<access-key>&Expires=1506888865&Signature=<signature>"
 expiry:
   description: Number of seconds the presigned url is valid for.
   returned: (for geturl operation)
@@ -402,6 +402,14 @@
   - prefix1/
   - prefix1/key1
   - prefix1/key2
+tags:
+    description: Tags of the s3 object.
+    returned: always
+    type: dict
+    sample: {
+                "Owner": "dev001",
+                "env": "test"
+            }
 """
 
 import base64

From dd549769f76e0f2e7853daead270a578b8f05323 Mon Sep 17 00:00:00 2001
From: Mandar Kulkarni <mandar242@gmail.com>
Date: Thu, 13 Jun 2024 13:53:29 -0700
Subject: [PATCH 06/12] add changelog fragment

---
 ...-update-retrun-block-s3_bucket-s3_bucket_info-s3_object.yml | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 changelogs/fragments/2135-update-retrun-block-s3_bucket-s3_bucket_info-s3_object.yml

diff --git a/changelogs/fragments/2135-update-retrun-block-s3_bucket-s3_bucket_info-s3_object.yml b/changelogs/fragments/2135-update-retrun-block-s3_bucket-s3_bucket_info-s3_object.yml
new file mode 100644
index 00000000000..36aa1b19344
--- /dev/null
+++ b/changelogs/fragments/2135-update-retrun-block-s3_bucket-s3_bucket_info-s3_object.yml
@@ -0,0 +1,3 @@
+---
+trivial:
+  - Update return block in the module documentation for s3_bucket, s3_bucket_info, s3_object modules (https://github.com/ansible-collections/amazon.aws/pull/2135).
\ No newline at end of file

From ce0a45f7bd20451b339fabded07fb0a35e0b5d66 Mon Sep 17 00:00:00 2001
From: Mandar Kulkarni <mandar242@gmail.com>
Date: Thu, 20 Jun 2024 15:59:22 -0700
Subject: [PATCH 07/12] modified based on feedback

---
 plugins/modules/s3_bucket.py      |  6 +++---
 plugins/modules/s3_bucket_info.py | 17 +++++++++--------
 2 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/plugins/modules/s3_bucket.py b/plugins/modules/s3_bucket.py
index 0452f163288..a1a9b38a5f1 100644
--- a/plugins/modules/s3_bucket.py
+++ b/plugins/modules/s3_bucket.py
@@ -294,7 +294,7 @@
     type: dict
     returned: when O(state=present)
     sample: {
-            "SSEAlgorithm": "AES256"
+                "SSEAlgorithm": "AES256"
             }
 name:
     description: Bucket name.
@@ -357,14 +357,14 @@
     returned: when O(state=present).
     sample: "public-read"
 object_lock_enabled:
-    description: Whether S3 Object Lock to be enabled.
+    description: Whether S3 Object Lock is enabled.
     type: bool
     returned: when O(state=present)
     sample: false
 public_access_block:
     description: Bucket public access block configuration.
     returned: when O(state=present)
-    type: complex
+    type: dict
     sample: {
                 "PublicAccessBlockConfiguration": {
                     "BlockPublicAcls": true,
diff --git a/plugins/modules/s3_bucket_info.py b/plugins/modules/s3_bucket_info.py
index 47f5be43256..1aff38a1224 100644
--- a/plugins/modules/s3_bucket_info.py
+++ b/plugins/modules/s3_bucket_info.py
@@ -190,7 +190,7 @@
     public_access_block:
       description: Bucket public access block configuration.
       returned: when O(bucket_facts=true) and  RV(buckets.public_access_block=true)
-      type: complex
+      type: dict
       sample: {
                 "PublicAccessBlockConfiguration": {
                     "BlockPublicAcls": true,
@@ -255,12 +255,12 @@
                 Type:
                   description: Type of grantee.
                   type: str
-        Permission:
-          description: Specifies the permission given to the grantee.
-          type: str
+            Permission:
+              description: Specifies the permission given to the grantee.
+              type: str
         Owner:
           description: Bucket owner information.
-          type: complex
+          type: dict
           sample: {
                     "DisplayName": "abc-aws-root+721234567890",
                     "ID": "1234567890cbc0f1234567890f1234567890c123456789012123456789091234"
@@ -327,7 +327,8 @@
     bucket_lifecycle_configuration:
       description: Bucket lifecycle configuration settings.
       returned: when O(bucket_facts=true) and RV(buckets.bucket_lifecycle_configuration=true).
-      type: complex
+      type: list
+      elements: dict
       contains:
         Rules:
           description: List of lifecycle management rules.
@@ -410,12 +411,12 @@
     bucket_policy_status:
       description: Status of bucket policy.
       returned: when O(bucket_facts=true) and RV(buckets.bucket_policy_status=true).
-      type: complex
+      type: dict
       contains:
         PolicyStatus:
           description: Status of bucket policy.
           returned: when bucket policy is present.
-          type: complex
+          type: dict
           contains:
             IsPublic:
               description: Report bucket policy public status.

From a826e5f8a1f17678f22f25f52f264d5a1a5cfb9c Mon Sep 17 00:00:00 2001
From: Mandar Kulkarni <mandar242@gmail.com>
Date: Thu, 20 Jun 2024 16:25:34 -0700
Subject: [PATCH 08/12] modified based on feedback

---
 plugins/modules/s3_bucket_info.py | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/plugins/modules/s3_bucket_info.py b/plugins/modules/s3_bucket_info.py
index 1aff38a1224..c7034552fff 100644
--- a/plugins/modules/s3_bucket_info.py
+++ b/plugins/modules/s3_bucket_info.py
@@ -344,12 +344,14 @@
       description: Bucket location.
       returned: when O(bucket_facts=true) and RV(buckets.bucket_location=true).
       type: complex
+      sample: "bucket_location": {
+                    "LocationConstraint": "us-east-1"
+                }
       contains:
         LocationConstraint:
           description: AWS region.
           returned: always
           type: str
-          sample: "us-east-2"
     bucket_logging:
       description: Server access logging configuration.
       returned: when O(bucket_facts=true) and RV(buckets.bucket_logging=true).
@@ -379,7 +381,25 @@
           description: List of notification events configurations.
           returned: when at least one notification is configured.
           type: list
-          sample: []
+          sample: [
+                      {
+                          'Id': 'topic-config-dev001',
+                          'TopicArn': 'arn:aws:sns:us-west-1:721234567890:sns-dev001-topic',
+                          'Events': [
+                              "s3:ObjectCreated:Copy"
+                          ],
+                          'Filter': {
+                              'Key': {
+                                  'FilterRules': [
+                                      {
+                                            "Name": "Prefix",
+                                            "Value": "test/"
+                                      },
+                                  ]
+                              }
+                          }
+                      },
+                    ]
     bucket_ownership_controls:
       description: Preffered object ownership settings.
       returned: when O(bucket_facts=true) and RV(buckets.bucket_ownership_controls=true)

From 5ac286f21bfe74e664082f5fed08e23eeda707a8 Mon Sep 17 00:00:00 2001
From: Mandar Kulkarni <mandar242@gmail.com>
Date: Thu, 20 Jun 2024 16:30:20 -0700
Subject: [PATCH 09/12] modified based on feedback

---
 plugins/modules/s3_bucket.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/plugins/modules/s3_bucket.py b/plugins/modules/s3_bucket.py
index a1a9b38a5f1..b27c3acede7 100644
--- a/plugins/modules/s3_bucket.py
+++ b/plugins/modules/s3_bucket.py
@@ -351,6 +351,7 @@
         Versioning:
             description: The versioning state of the bucket.
             type: str
+            returned: always
 acl:
     description: S3 bucket's canned ACL.
     type: dict

From 974f6601c19038619652172e74c1aef1d38e4eac Mon Sep 17 00:00:00 2001
From: Mandar Kulkarni <mandar242@gmail.com>
Date: Thu, 20 Jun 2024 16:48:05 -0700
Subject: [PATCH 10/12] modified based on feedback

---
 plugins/modules/s3_bucket_info.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/plugins/modules/s3_bucket_info.py b/plugins/modules/s3_bucket_info.py
index c7034552fff..2dc8e7dc289 100644
--- a/plugins/modules/s3_bucket_info.py
+++ b/plugins/modules/s3_bucket_info.py
@@ -343,7 +343,7 @@
     bucket_location:
       description: Bucket location.
       returned: when O(bucket_facts=true) and RV(buckets.bucket_location=true).
-      type: complex
+      type: dict
       sample: "bucket_location": {
                     "LocationConstraint": "us-east-1"
                 }

From 405f3b76cc4db052adc800ae231e07a6255234de Mon Sep 17 00:00:00 2001
From: Mandar Kulkarni <mandar242@gmail.com>
Date: Sat, 22 Jun 2024 12:48:10 -0700
Subject: [PATCH 11/12] modified based on feedback

---
 plugins/modules/s3_bucket_info.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/plugins/modules/s3_bucket_info.py b/plugins/modules/s3_bucket_info.py
index 2dc8e7dc289..ee3c5849b42 100644
--- a/plugins/modules/s3_bucket_info.py
+++ b/plugins/modules/s3_bucket_info.py
@@ -344,9 +344,9 @@
       description: Bucket location.
       returned: when O(bucket_facts=true) and RV(buckets.bucket_location=true).
       type: dict
-      sample: "bucket_location": {
-                    "LocationConstraint": "us-east-1"
-                }
+      sample: {
+                "LocationConstraint": "us-east-1"
+              }
       contains:
         LocationConstraint:
           description: AWS region.

From 96d7d8b1cd5f32566167dbf0b76e3ef69e4847cc Mon Sep 17 00:00:00 2001
From: Mandar Kulkarni <mandar242@gmail.com>
Date: Tue, 25 Jun 2024 00:22:55 -0700
Subject: [PATCH 12/12] minor fixes

---
 plugins/modules/s3_bucket_info.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/plugins/modules/s3_bucket_info.py b/plugins/modules/s3_bucket_info.py
index ee3c5849b42..acae57a2826 100644
--- a/plugins/modules/s3_bucket_info.py
+++ b/plugins/modules/s3_bucket_info.py
@@ -189,7 +189,7 @@
       sample: "2021-01-21T12:44:10+00:00"
     public_access_block:
       description: Bucket public access block configuration.
-      returned: when O(bucket_facts=true) and  RV(buckets.public_access_block=true)
+      returned: when O(bucket_facts=true) and RV(buckets.public_access_block=true).
       type: dict
       sample: {
                 "PublicAccessBlockConfiguration": {
@@ -455,7 +455,7 @@
           sample: "arn:aws:iam::123:role/example-role"
         Rules:
           description: List of replication rules.
-          returned: when replication rule is defined/
+          returned: when replication rule is defined.
           type: list
           sample: [{ "ID": "rule-1", "Filter": "{}" }]
     bucket_request_payment: