From f60d13b2c1d8d2c5c6800fc5a67320911644ff0d Mon Sep 17 00:00:00 2001
From: Shailja Khurana <117320115+khushail@users.noreply.github.com>
Date: Tue, 17 Sep 2024 08:56:53 -0700
Subject: [PATCH] docs(s3): updated docstring for BucketPolicy() (#31395)

### Issue #[31358](https://github.com/aws/aws-cdk/issues/31358)

Closes #31358 .

### Reason for this change

Exsiting [CDK Doc on BucketPolicy](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.BucketPolicy.html) mentions as `Prefer to use` which is misleading as it does not clearly states the reprecussions.

### Description of changes

I have added a sample of what would happen if this is used along with other Bucket properties.

### Description of how you validated changes

This is a minor documentation change

### Checklist
- [ ] 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/lib/bucket-policy.ts | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/packages/aws-cdk-lib/aws-s3/lib/bucket-policy.ts b/packages/aws-cdk-lib/aws-s3/lib/bucket-policy.ts
index f9875c7a48ae9..72aaaedf9191f 100644
--- a/packages/aws-cdk-lib/aws-s3/lib/bucket-policy.ts
+++ b/packages/aws-cdk-lib/aws-s3/lib/bucket-policy.ts
@@ -31,7 +31,20 @@ export interface BucketPolicyProps {
  * policy if one doesn't exist yet, otherwise it will add to the existing
  * policy.
  *
- * Prefer to use `addToResourcePolicy()` instead.
+ * The bucket policy method is implemented differently than `addToResourcePolicy()`
+ * as `BucketPolicy()` creates a new policy without knowing one earlier existed.
+ * e.g. if during Bucket creation, if `autoDeleteObject:true`, these policies are
+ * added to the bucket policy:
+ *    ["s3:DeleteObject*", "s3:GetBucket*", "s3:List*", "s3:PutBucketPolicy"],
+ * and when you add a new BucketPolicy with ["s3:GetObject", "s3:ListBucket"] on
+ * this existing bucket, invoking `BucketPolicy()` will create a new Policy
+ * without knowing one earlier exists already, so it creates a new one.
+ * In this case, the custom resource handler will not have access to
+ * `s3:GetBucketTagging` action which will cause failure during deletion of stack.
+ *
+ * Hence its strongly recommended to use `addToResourcePolicy()` method to add
+ * new permissions to existing policy.
+ *
  */
 export class BucketPolicy extends Resource {
   /**