docs(s3): updated docstring for BucketPolicy() (#31395)

### Issue #[31358](#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*

Author: khushail

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 {
   /**