docs(s3): update documentation for more context around autoDeleteObjects

packages/aws-cdk-lib/aws-s3/README.md

@@ -622,6 +622,8 @@ as it does not contain any objects.
 To override this and force all objects to get deleted during bucket deletion,
 enable the`autoDeleteObjects` option.
 
+When `autoDeleteObjects` is enabled, we include the `s3:PutBucketPolicy` action in the Bucket Policy. This allows users to manage bucket policies, creating new ones or adjusting existing ones for Amazon S3 buckets. We do this because during bucket deletion, the custom resource provider updates the bucket policy by adding a **DENY** effect for `s3:PutObject` action, preventing new objects from being created in the bucket. This helps avoid any race conditions during the deletion process with external bucket writers.
+
 ```ts
 const bucket = new s3.Bucket(this, 'MyTempFileBucket', {
   removalPolicy: cdk.RemovalPolicy.DESTROY,

packages/aws-cdk-lib/aws-s3/lib/bucket.ts

@@ -1471,6 +1471,11 @@ export interface BucketProps {
    * all objects in the bucket being deleted. Be sure to update your bucket resources
    * by deploying with CDK version `1.126.0` or later **before** switching this value to `false`.
    *
+   * Setting the `autoDeleteObjects: true` on a bucket will include `s3:PutBucketPolicy` action
+   * to the Bucket Policy. The reason being upon bucket deletion, the custom resource provider
+   * needs to update the bucket policy by adding a `DENY` policy for `s3:PutObject` to
+   * prevent a race condition on emptying with external bucket writers.
+   *
    * @default false
    */
   readonly autoDeleteObjects?: boolean;