feat(core): add a description parameter for the NestedStackProps (#20930

)

This PR adds a description parameter for the NestedStackProps.

Fixes #16337

----

### All Submissions:

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

### Adding new Unconventional Dependencies:

* [ ] This PR adds new unconventional dependencies following the process described [here](https://github.com/aws/aws-cdk/blob/main/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/main/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-cloudformation/test/integ.nested-stack.ts

@@ -12,6 +12,7 @@ interface MyNestedStackProps {
   readonly siblingTopic?: sns.Topic; // a topic defined in a sibling nested stack
   readonly topicCount: number;
   readonly topicNamePrefix: string;
+  readonly description?: string;
 }
 
 class MyNestedStack extends NestedStack {
@@ -22,6 +23,7 @@ class MyNestedStack extends NestedStack {
       parameters: {
         [topicNamePrefixLogicalId]: props.topicNamePrefix, // pass in a parameter to the nested stack
       },
+      description: props.description,
     });
 
     const topicNamePrefixParameter = new CfnParameter(this, 'TopicNamePrefix', { type: 'String' });
@@ -57,7 +59,7 @@ class MyTestStack extends Stack {
     const queue = new sqs.Queue(this, 'SubscriberQueue');
 
     new MyNestedStack(this, 'NestedStack1', { topicCount: 3, topicNamePrefix: 'Prefix1', subscriber: queue });
-    new MyNestedStack(this, 'NestedStack2', { topicCount: 2, topicNamePrefix: 'Prefix2' });
+    new MyNestedStack(this, 'NestedStack2', { topicCount: 2, topicNamePrefix: 'Prefix2', description: 'This is secound nested stack.' });
   }
 }
 

packages/@aws-cdk/core/README.md

@@ -995,6 +995,16 @@ const stack = new Stack(app, 'StackName', {
 
 By default, termination protection is disabled.
 
+### Description
+
+You can add a description of the stack in the same way as `StackProps`.
+
+```ts
+const stack = new Stack(app, 'StackName', {
+  description: 'This is a description.',
+});
+```
+
 ### CfnJson
 
 `CfnJson` allows you to postpone the resolution of a JSON blob from

packages/@aws-cdk/core/lib/nested-stack.ts

@@ -68,6 +68,13 @@ export interface NestedStackProps {
    * @default RemovalPolicy.DESTROY
    */
   readonly removalPolicy?: RemovalPolicy;
+
+  /**
+   * A description of the stack.
+   *
+   * @default - No description.
+   */
+  readonly description?: string;
 }
 
 /**
@@ -112,6 +119,7 @@ export class NestedStack extends Stack {
     super(scope, id, {
       env: { account: parentStack.account, region: parentStack.region },
       synthesizer: new NestedStackSynthesizer(parentStack.synthesizer),
+      description: props.description,
     });
 
     this._parentStack = parentStack;

packages/@aws-cdk/core/test/nested-stack.test.ts

@@ -22,4 +22,13 @@ describe('nested-stack', () => {
       },
     });
   });
+  test('a nested-stack has a description in templateOptions.', () => {
+    const description = 'This is a description.';
+    const stack = new Stack();
+    var nestedStack = new NestedStack(stack, 'MyNestedStack', {
+      description,
+    });
+
+    expect(nestedStack.templateOptions.description).toEqual(description);
+  });
 });

packages/aws-cdk-lib/README.md

@@ -1026,6 +1026,16 @@ const stack = new Stack(app, 'StackName', {
 
 By default, termination protection is disabled.
 
+### Description
+
+You can add a description of the stack in the same way as `StackProps`.
+
+```ts
+const stack = new Stack(app, 'StackName', {
+  description: 'This is a description.',
+});
+```
+
 ### CfnJson
 
 `CfnJson` allows you to postpone the resolution of a JSON blob from