From 56a4122d1da1f5986c5bc44ee4c5b907ce527133 Mon Sep 17 00:00:00 2001
From: Michael Sambol <sambol.michael@gmail.com>
Date: Fri, 22 Mar 2024 11:34:46 -0600
Subject: [PATCH] chore(core): clarify support for ISO duration (#29576)

Closes #29572.

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*
---
 packages/aws-cdk-lib/core/lib/duration.ts | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/packages/aws-cdk-lib/core/lib/duration.ts b/packages/aws-cdk-lib/core/lib/duration.ts
index 9e32fbb89d391..24e7b1ca0577b 100644
--- a/packages/aws-cdk-lib/core/lib/duration.ts
+++ b/packages/aws-cdk-lib/core/lib/duration.ts
@@ -62,6 +62,13 @@ export class Duration {
   /**
    * Parse a period formatted according to the ISO 8601 standard
    *
+   * Days are the largest ISO duration supported, i.e.,
+   * weeks, months, and years are not supported.
+   *
+   * @example
+   * // This represents 1 day, 2 hours, 3 minutes, 4 seconds, and 567 milliseconds.
+   * 'P1DT2H3M4.567S'
+   *
    * @see https://www.iso.org/standard/70907.html
    * @param duration an ISO-formatted duration to be parsed.
    * @returns the parsed `Duration`.