Add documentation around dlq

packages/@aws-cdk/aws-pipes-alpha/lib/pipe.ts

@@ -233,6 +233,12 @@ export class Pipe extends PipeBase {
      */
     const source = props.source.bind(this);
     props.source.grantRead(this.pipeRole);
+
+    /**
+     * An optional dead-letter queue stores any events that are not successfully delivered to
+     * a target after all retry attempts are exhausted. The IAM role needs permission to write
+     * events to the dead-letter queue, either an SQS queue or SNS topic.
+     */
     if (SourceWithDeadLetterTarget.isSourceWithDeadLetterTarget(props.source)) {
       props.source.grantPush(this.pipeRole, props.source.deadLetterTarget);
     }

packages/@aws-cdk/aws-pipes-sources-alpha/lib/streamSource.ts

@@ -17,7 +17,11 @@ export interface StreamSourceParameters {
   readonly batchSize?: number;
 
   /**
-    * Define the target queue to send dead-letter queue events to.
+    * Define the target to send dead-letter queue events to.
+    *
+    * The dead-letter queue stores any events that are not successfully delivered to a Pipes target after all retry attempts are exhausted.
+    * You can then resolve the issue that caused the failed invocations and replay the events at a later time.
+    * In some cases, such as when access is denied to a resource, events are sent directly to the dead-letter queue and are not retried.
     *
     * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-pipes-pipe-pipesourcekinesisstreamparameters.html#cfn-pipes-pipe-pipesourcekinesisstreamparameters-deadletterconfig
     * @default - no dead-letter queue or topic