Emphasize that durations are context independent.

sdk/lib/core/date_time.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;
 
 /**
  * An instant in time, such as July 20, 1969, 8:18pm GMT.
  *
  * Create a DateTime object by using one of the constructors
@@ skipping 554 matching lines @@
       return "$y-$m-${d}T$h:$min:$sec.$ms${us}Z";
     } else {
       return "$y-$m-${d}T$h:$min:$sec.$ms$us";
     }
   }
 
   /**
    * Returns a new [DateTime] instance with [duration] added to [this].
    *
    *     DateTime today = new DateTime.now();
-   *     DateTime sixtyDaysFromNow = today.add(new Duration(days: 60));
+   *     DateTime fiftyDaysFromNow = today.add(new Duration(days: 50));
+   *
+   * Notice that the duration being added is actually 50 * 24 * 60 * 60
+   * seconds. If the resulting `DateTime` has a different daylight saving offset
+   * than `this`, then the result won't have the same time-of-day as `this`, and
+   * may not even hit the calendar date 50 days later.
+   *
+   * Be careful when working with dates in local time.
    */
   external DateTime add(Duration duration);
 
   /**
    * Returns a new [DateTime] instance with [duration] subtracted from [this].
    *
    *     DateTime today = new DateTime.now();
-   *     DateTime sixtyDaysAgo = today.subtract(new Duration(days: 30));
+   *     DateTime fiftyDaysAgo = today.subtract(new Duration(days: 50));
    *
-   * Notice that duration being subtracted is actually 30 * 24 * 60 * 60 seconds
-   * and if that crosses a daylight saving time change, the resulting `DateTime`
-   * won't have the same time of day as `today`, and may not actually hit the
-   * calendar date 30 days earlier. Be careful when working with dates in local
-   * time.
+   * Notice that the duration being subtracted is actually 50 * 24 * 60 * 60
+   * seconds. If the resulting `DateTime` has a different daylight saving offset
+   * than `this`, then the result won't have the same time-of-day as `this`, and
+   * may not even hit the calendar date 50 days earlier.
+   *
+   * Be careful when working with dates in local time.
    */
   external DateTime subtract(Duration duration);
 
   /**
    * Returns a [Duration] with the difference between [this] and [other].
    *
    *     DateTime berlinWallFell = new DateTime.utc(1989, DateTime.NOVEMBER, 9);
    *     DateTime dDay = new DateTime.utc(1944, DateTime.JUNE, 6);
    *
    *     Duration difference = berlinWallFell.difference(dDay);
@@ skipping 158 matching lines @@
    * In accordance with ISO 8601
    * a week starts with Monday, which has the value 1.
    *
    *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
    *     assert(moonLanding.weekday == 7);
    *     assert(moonLanding.weekday == DateTime.SUNDAY);
    *
    */
   external int get weekday;
 }