chore(s3): documented how the bucket encryption configuration is computed (#25079)

----

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

Author: otaviomacedo

packages/aws-cdk-lib/aws-s3/lib/bucket.ts

@@ -1983,7 +1983,22 @@ export class Bucket extends BucketBase {
 
   /**
    * Set up key properties and return the Bucket encryption property from the
-   * user's configuration.
+   * user's configuration, according to the following table:
+   *
+   * | props.encryption | props.encryptionKey | props.bucketKeyEnabled | bucketEncryption (return value) | encryptionKey (return value) |
+   * |------------------|---------------------|------------------------|---------------------------------|------------------------------|
+   * | undefined        | undefined           | e                      | undefined                       | undefined                    |
+   * | UNENCRYPTED      | undefined           | false                  | undefined                       | undefined                    |
+   * | undefined        | k                   | e                      | SSE-KMS, bucketKeyEnabled = e   | k                            |
+   * | KMS              | k                   | e                      | SSE-KMS, bucketKeyEnabled = e   | k                            |
+   * | KMS              | undefined           | e                      | SSE-KMS, bucketKeyEnabled = e   | new key                      |
+   * | KMS_MANAGED      | undefined           | e                      | SSE-KMS, bucketKeyEnabled = e   | undefined                    |
+   * | S3_MANAGED       | undefined           | false                  | SSE-S3                          | undefined                    |
+   * | UNENCRYPTED      | undefined           | true                   | ERROR!                          | ERROR!                       |
+   * | UNENCRYPTED      | k                   | e                      | ERROR!                          | ERROR!                       |
+   * | KMS_MANAGED      | k                   | e                      | ERROR!                          | ERROR!                       |
+   * | S3_MANAGED       | undefined           | true                   | ERROR!                          | ERROR!                       |
+   * | S3_MANAGED       | k                   | e                      | ERROR!                          | ERROR!                       |
    */
   private parseEncryption(props: BucketProps): {
     bucketEncryption?: CfnBucket.BucketEncryptionProperty,