Emphasize that durations are context independent.

sdk/lib/core/duration.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.core;
 
 /**
  * A span of time, such as 27 days, 4 hours, 12 minutes, and 3 seconds.
  *
  * A `Duration` represents a difference from one point in time to another. The
  * duration may be "negative" if the difference is from a later time to an
  * earlier.
  *
+ * Durations are context independent. For example, a duration of 2 days is
+ * always 48 hours, even when it is added to a `DateTime` just when the
+ * time zone is about to do a daylight-savings switch. (See [DateTime.add]).
+ *
+ * Despite the same name, a `Duration` object does not implement "Durations"
+ * as specified by ISO 8601. In particular, a duration object does not keep
+ * track of the individually provided members (such as "days" or "hours"), but
+ * only uses these arguments to compute the length of the corresponding time
+ * interval.
+ *
  * To create a new Duration object, use this class's single constructor
  * giving the appropriate arguments:
  *
  *     Duration fastestMarathon = new Duration(hours:2, minutes:3, seconds:2);
  *
  * The Duration is the sum of all individual parts.
  * This means that individual parts can be larger than the next-bigger unit.
  * For example, [minutes] can be greater than 59.
  *
  *     assert(fastestMarathon.inMinutes == 123);
@@ skipping 256 matching lines @@
   Duration abs() => new Duration._microseconds(_duration.abs());
 
   /**
    * Returns a new `Duration` representing this `Duration` negated.
    *
    * The returned `Duration` has the same length as this one, but will have the
    * opposite sign of this one.
    */
   Duration operator -() => new Duration._microseconds(-_duration);
 }