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*

Author: laurelmay

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>();

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();