From 21c6e7e94ae2cd31e895d11b6156e5d8adbd42bf Mon Sep 17 00:00:00 2001
From: Rico Huijbers <rix0rrr@gmail.com>
Date: Thu, 30 Dec 2021 17:58:48 +0100
Subject: [PATCH] docs: discourage creation of resource policies

Add docs explaining that `addToResourcePolicy()` should be used
instead.
---
 packages/@aws-cdk/aws-logs/lib/policy.ts           | 13 ++++++++++++-
 packages/@aws-cdk/aws-s3/lib/bucket-policy.ts      | 13 ++++++++++++-
 packages/@aws-cdk/aws-secretsmanager/lib/policy.ts | 13 ++++++++++++-
 packages/@aws-cdk/aws-sns/lib/policy.ts            | 13 ++++++++++++-
 packages/@aws-cdk/aws-sqs/lib/policy.ts            | 13 ++++++++++++-
 5 files changed, 60 insertions(+), 5 deletions(-)

diff --git a/packages/@aws-cdk/aws-logs/lib/policy.ts b/packages/@aws-cdk/aws-logs/lib/policy.ts
index de3af44f1ae2f..ed150fa12e9cb 100644
--- a/packages/@aws-cdk/aws-logs/lib/policy.ts
+++ b/packages/@aws-cdk/aws-logs/lib/policy.ts
@@ -22,7 +22,18 @@ export interface ResourcePolicyProps {
 }
 
 /**
- * Creates Cloudwatch log group resource policies
+ * Resource Policy for CloudWatch Log Groups
+ *
+ * Policies define the operations that are allowed on this resource.
+ *
+ * You almost never need to define this construct directly.
+ *
+ * All AWS resources that support resource policies have a method called
+ * `addToResourcePolicy()`, which will automatically create a new resource
+ * policy if one doesn't exist yet, otherwise it will add to the existing
+ * policy.
+ *
+ * Prefer to use `addToResourcePolicy()` instead.
  */
 export class ResourcePolicy extends Resource {
   /**
diff --git a/packages/@aws-cdk/aws-s3/lib/bucket-policy.ts b/packages/@aws-cdk/aws-s3/lib/bucket-policy.ts
index 395ff706b5fdc..3b380c4eb9b23 100644
--- a/packages/@aws-cdk/aws-s3/lib/bucket-policy.ts
+++ b/packages/@aws-cdk/aws-s3/lib/bucket-policy.ts
@@ -19,7 +19,18 @@ export interface BucketPolicyProps {
 }
 
 /**
- * Applies an Amazon S3 bucket policy to an Amazon S3 bucket.
+ * The bucket policy for an Amazon S3 bucket
+ *
+ * Policies define the operations that are allowed on this resource.
+ *
+ * You almost never need to define this construct directly.
+ *
+ * All AWS resources that support resource policies have a method called
+ * `addToResourcePolicy()`, which will automatically create a new resource
+ * policy if one doesn't exist yet, otherwise it will add to the existing
+ * policy.
+ *
+ * Prefer to use `addToResourcePolicy()` instead.
  */
 export class BucketPolicy extends Resource {
 
diff --git a/packages/@aws-cdk/aws-secretsmanager/lib/policy.ts b/packages/@aws-cdk/aws-secretsmanager/lib/policy.ts
index 67769ed403399..0e39e78d79c29 100644
--- a/packages/@aws-cdk/aws-secretsmanager/lib/policy.ts
+++ b/packages/@aws-cdk/aws-secretsmanager/lib/policy.ts
@@ -15,7 +15,18 @@ export interface ResourcePolicyProps {
 }
 
 /**
- * Secret Resource Policy
+ * Resource Policy for SecretsManager Secrets
+ *
+ * Policies define the operations that are allowed on this resource.
+ *
+ * You almost never need to define this construct directly.
+ *
+ * All AWS resources that support resource policies have a method called
+ * `addToResourcePolicy()`, which will automatically create a new resource
+ * policy if one doesn't exist yet, otherwise it will add to the existing
+ * policy.
+ *
+ * Prefer to use `addToResourcePolicy()` instead.
  */
 export class ResourcePolicy extends Resource {
   /**
diff --git a/packages/@aws-cdk/aws-sns/lib/policy.ts b/packages/@aws-cdk/aws-sns/lib/policy.ts
index 03a791bd57814..e201e39959cb3 100644
--- a/packages/@aws-cdk/aws-sns/lib/policy.ts
+++ b/packages/@aws-cdk/aws-sns/lib/policy.ts
@@ -21,7 +21,18 @@ export interface TopicPolicyProps {
 }
 
 /**
- * Applies a policy to SNS topics.
+ * The policy for an SNS Topic
+ *
+ * Policies define the operations that are allowed on this resource.
+ *
+ * You almost never need to define this construct directly.
+ *
+ * All AWS resources that support resource policies have a method called
+ * `addToResourcePolicy()`, which will automatically create a new resource
+ * policy if one doesn't exist yet, otherwise it will add to the existing
+ * policy.
+ *
+ * Prefer to use `addToResourcePolicy()` instead.
  */
 export class TopicPolicy extends Resource {
   /**
diff --git a/packages/@aws-cdk/aws-sqs/lib/policy.ts b/packages/@aws-cdk/aws-sqs/lib/policy.ts
index f4116205e69c2..5b79fc9af4e5a 100644
--- a/packages/@aws-cdk/aws-sqs/lib/policy.ts
+++ b/packages/@aws-cdk/aws-sqs/lib/policy.ts
@@ -15,7 +15,18 @@ export interface QueuePolicyProps {
 }
 
 /**
- * Applies a policy to SQS queues.
+ * The policy for an SQS Queue
+ *
+ * Policies define the operations that are allowed on this resource.
+ *
+ * You almost never need to define this construct directly.
+ *
+ * All AWS resources that support resource policies have a method called
+ * `addToResourcePolicy()`, which will automatically create a new resource
+ * policy if one doesn't exist yet, otherwise it will add to the existing
+ * policy.
+ *
+ * Prefer to use `addToResourcePolicy()` instead.
  */
 export class QueuePolicy extends Resource {
   /**