docs(s3): update documentation for more context around `autoDeleteObj…

…ects` (#30096)

### Issue # (if applicable)
[29873](#29873)



### Description of changes
This the documentation update to notify users that upon setting the `autoDeleteObjects` to `true` we would also add a new policy `s3:PutBucketPolicy` to handle race conditions.

### Checklist
-  [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

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 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;