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