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, `s3:PutBucketPolicy` is added to the bucket policy. This is done to allow the custom resource this feature is built on to add a deny policy by for `s3:PutObject` to the bucket policy when a delete stack event occurs. Adding this deny policy prevents new objects from being written to the bucket. Doing this prevents race conditions with external bucket writers during the deletion process.
+
 ```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 `autoDeleteObjects` to true on a bucket will add `s3:PutBucketPolicy` to the
+   * bucket policy. This is because during bucket deletion, the custom resource provider
+   * needs to update the bucket policy by adding a deny policy for `s3:PutObject` to
+   * prevent race conditions with external bucket writers.
+   *
    * @default false
    */
   readonly autoDeleteObjects?: boolean;