Add warning on DateTime.difference that DST + local-time is dangerous.

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 1e89080a5f688cb8219f982dbad99b719e5febd6..a9b1ecc375eff2efad949db140e89d15a509c2c4 100644
--- a/sdk/lib/core/date_time.dart
+++ b/sdk/lib/core/date_time.dart
@@ -580,7 +580,13 @@ class DateTime implements Comparable {
    * Returns a new [DateTime] instance with [duration] subtracted from [this].
    *
    *     DateTime today = new DateTime.now();
-   *     DateTime sixtyDaysAgo = today.subtract(new Duration(days: 60));
+   *     DateTime sixtyDaysAgo = today.subtract(new Duration(days: 30));
+   *
+   * 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.
    */
   DateTime subtract(Duration duration) {
     int ms = millisecondsSinceEpoch;
@@ -591,13 +597,29 @@ class DateTime implements Comparable {
   /**
    * 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);
+   *     assert(difference.inDays == 16592);
+   *
+   * The difference is measured in seconds and fractions of seconds.
+   * The difference above counts the number of fractional seconds between
+   * midnight at the beginning of those dates.
+   * If the dates above had been in local time, not UTC, then the difference
+   * between two midnights may not be a multiple of 24 hours due to daylight
+   * saving differences.
+   *
+   * For example, in Australia, similar code using local time instead of UTC:
+   *
    *     DateTime berlinWallFell = new DateTime(1989, DateTime.NOVEMBER, 9);
    *     DateTime dDay = new DateTime(1944, DateTime.JUNE, 6);
-   *
    *     Duration difference = berlinWallFell.difference(dDay);
    *     assert(difference.inDays == 16592);
+   *
+   * will fail because the difference is actually 16591 days and 23 hours, and
+   * [Duration.inDays] only returns the number of whole days.
    */
-
   Duration difference(DateTime other) {
     int ms = millisecondsSinceEpoch;
     int otherMs = other.millisecondsSinceEpoch;