docs: discourage creation of resource policies (#18227)

Add docs explaining that `addToResourcePolicy()` should be used
instead.


----

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

Author: rix0rrr

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

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 {
 

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

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

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