Emphasize that durations are context independent.

sdk/lib/core/date_time.dart

Index: sdk/lib/core/date_time.dart
diff --git a/sdk/lib/core/date_time.dart b/sdk/lib/core/date_time.dart
index b792ac272e6a8bfb97fdf7acfff3ddb031fe9879..b4127392f483cf3983f43b4546d4c5e3fa5bbfb2 100644
--- a/sdk/lib/core/date_time.dart
+++ b/sdk/lib/core/date_time.dart
@@ -573,6 +573,13 @@ class DateTime implements Comparable<DateTime> {
    *
    *     DateTime today = new DateTime.now();
    *     DateTime sixtyDaysFromNow = today.add(new Duration(days: 60));
+   *
+   * Notice that the duration being added is actually 60 * 24 * 60 * 60

[Lasse Reichstein Nielsen, 2016/10/17 12:40:12]

Pick a number of days different from 60, it's confusing with the min/hr and
sec/min 60's.

[floitsch, 2016/10/17 12:50:25]

Done.

+   * seconds and if that crosses a daylight saving time change, the resulting

[Lasse Reichstein Nielsen, 2016/10/17 12:40:12]

if that -> if this `DateTime` has non-UTC time zone and adding that number of
seconds to the `DateTime` ...

[floitsch, 2016/10/17 12:50:25]

Done.

+   * `DateTime` won't have the same time of day as `today`, and may not even
+   * hit the calendar date 60 days later.
+   *
+   * Be careful when working with dates in local time.
    */
   external DateTime add(Duration duration);
 
@@ -580,13 +587,14 @@ class DateTime implements Comparable<DateTime> {
    * Returns a new [DateTime] instance with [duration] subtracted from [this].
    *
    *     DateTime today = new DateTime.now();
-   *     DateTime sixtyDaysAgo = today.subtract(new Duration(days: 30));
+   *     DateTime sixtyDaysAgo = today.subtract(new Duration(days: 60));
+   *
+   * Notice that the duration being subtracted is actually 60 * 24 * 60 * 60

[Lasse Reichstein Nielsen, 2016/10/17 12:40:12]

same as above (except adding->subtracting).

[floitsch, 2016/10/17 12:50:25]

Done.

+   * 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 even
+   * hit the calendar date 60 days earlier.
    *
-   * 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.
+   * Be careful when working with dates in local time.
    */
   external DateTime subtract(Duration duration);