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`.