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*

Author: msambol

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