From ad8f64b7b152d1ed3451c1327738248296132836 Mon Sep 17 00:00:00 2001
From: Kyle Laker <kyle@laker.email>
Date: Mon, 16 May 2022 11:38:27 -0400
Subject: [PATCH] docs(iam): add return values of policy validation methods
 (#20350)

Because these just return a list of strings it may not be clear to a
caller what the validation methods are actually returning. This `@returns`
text is based on the documentation in core's Construct.validate
documentation.


----

### All Submissions:

* [X] Have you followed the guidelines in our [Contributing guide?](https://github.com/aws/aws-cdk/blob/master/CONTRIBUTING.md)

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/master/CONTRIBUTING.md/#adding-new-unconventional-dependencies)

### New Features

* [ ] Have you added the new feature to an [integration test](https://github.com/aws/aws-cdk/blob/master/INTEGRATION_TESTS.md)?
	* [ ] Did you use `yarn integ` to deploy the infrastructure and generate the snapshot (i.e. `yarn integ` without `--dry-run`)?

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
---
 packages/@aws-cdk/aws-iam/lib/policy-document.ts  | 6 ++++++
 packages/@aws-cdk/aws-iam/lib/policy-statement.ts | 6 ++++++
 2 files changed, 12 insertions(+)

diff --git a/packages/@aws-cdk/aws-iam/lib/policy-document.ts b/packages/@aws-cdk/aws-iam/lib/policy-document.ts
index 9d73acb4693ac..770ab4e9556a0 100644
--- a/packages/@aws-cdk/aws-iam/lib/policy-document.ts
+++ b/packages/@aws-cdk/aws-iam/lib/policy-document.ts
@@ -128,6 +128,8 @@ export class PolicyDocument implements cdk.IResolvable {
    * requirements for any policy.
    *
    * @see https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#access_policies-json
+   *
+   * @returns An array of validation error messages, or an empty array if the document is valid.
    */
   public validateForAnyPolicy(): string[] {
     const errors = new Array<string>();
@@ -142,6 +144,8 @@ export class PolicyDocument implements cdk.IResolvable {
    * requirements for a resource-based policy.
    *
    * @see https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#access_policies-json
+   *
+   * @returns An array of validation error messages, or an empty array if the document is valid.
    */
   public validateForResourcePolicy(): string[] {
     const errors = new Array<string>();
@@ -156,6 +160,8 @@ export class PolicyDocument implements cdk.IResolvable {
    * requirements for an identity-based policy.
    *
    * @see https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html#access_policies-json
+   *
+   * @returns An array of validation error messages, or an empty array if the document is valid.
    */
   public validateForIdentityPolicy(): string[] {
     const errors = new Array<string>();
diff --git a/packages/@aws-cdk/aws-iam/lib/policy-statement.ts b/packages/@aws-cdk/aws-iam/lib/policy-statement.ts
index 688cf39faea18..200592f69c6e5 100644
--- a/packages/@aws-cdk/aws-iam/lib/policy-statement.ts
+++ b/packages/@aws-cdk/aws-iam/lib/policy-statement.ts
@@ -442,6 +442,8 @@ export class PolicyStatement {
 
   /**
    * Validate that the policy statement satisfies base requirements for a policy.
+   *
+   * @returns An array of validation error messages, or an empty array if the statement is valid.
    */
   public validateForAnyPolicy(): string[] {
     const errors = new Array<string>();
@@ -453,6 +455,8 @@ export class PolicyStatement {
 
   /**
    * Validate that the policy statement satisfies all requirements for a resource-based policy.
+   *
+   * @returns An array of validation error messages, or an empty array if the statement is valid.
    */
   public validateForResourcePolicy(): string[] {
     const errors = this.validateForAnyPolicy();
@@ -464,6 +468,8 @@ export class PolicyStatement {
 
   /**
    * Validate that the policy statement satisfies all requirements for an identity-based policy.
+   *
+   * @returns An array of validation error messages, or an empty array if the statement is valid.
    */
   public validateForIdentityPolicy(): string[] {
     const errors = this.validateForAnyPolicy();