chore(s3): updated documentation to provide better insights when using grant methods for the Bucket resource (#34733)

### Issue # (if applicable)

Closes #34545 .

### Reason for this change

Current behavior in some `grant` methods for the `Bucket` resource might cause confusion and be seen as a bug.

### Description of changes

Added more details on the policy specifics, explaining why the current behavior is like that, and added additional resources if the implementer needs to restrict even more their permissions.


### Describe any new or updated permissions being added

N/A


### Description of how you validated changes

N/A. Just documentation being updated.

### 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*

Author: alvazjor

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

@@ -156,6 +156,22 @@ bucket.grantReadWrite(myLambda);
 Will give the Lambda's execution role permissions to read and write
 from the bucket.
 
+### Understanding "grant" Methods
+
+The S3 construct library provides several grant methods for the `Bucket` resource, but two of them have a special behavior. This two accept an `objectsKeyPattern` parameter to restrict granted permissions to specific resources:
+- `grantRead`
+- `grantReadWrite`
+
+When examining the synthesized policy, you'll notice it includes both your specified object key patterns and the bucket itself.
+This is by design. Some permissions (like `s3:ListBucket`) apply at the bucket level, while others (like `s3:GetObject`) apply to specific objects.
+
+Specifically, the [`s3:ListBucket` action operates on bucket resources](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazons3.html#amazons3-bucket)
+and requires the bucket ARN to work properly. This might be seen as a bug, giving the impression that more permissions were granted than the ones you intended, but the reality is that the policy does not ignore your `objectsKeyPattern` - object-specific actions like `s3:GetObject`
+will still be limited to the resources defined in your pattern.
+
+If you need to restrict the `s3:ListBucket` action to specific paths, you can add a `Condition` to your policy that limits the `objectsKeyPattern` to specific folders. For more details and examples, see the [AWS documentation on bucket policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/example-bucket-policies.html#example-bucket-policies-folders).
+
+
 ## AWS Foundational Security Best Practices
 
 ### Enforcing SSL