chore(core): clarify support for ISO duration (aws#29576)

Closes aws#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

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