Merge branch 'master' into datetimedocs

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 e0509d6a175aecaf9d40511e9623925d90b02697..c905390b937c6bcc2cb83525dbe5bc6ca923881a 100644
--- a/sdk/lib/core/date_time.dart
+++ b/sdk/lib/core/date_time.dart
@@ -5,14 +5,88 @@
 part of dart.core;
 
 /**
- * A DateTime object represents a point in time.
+ * An instant in time, such as July 20, 1969, 8:18pm.
  *
- * It can represent time values that are at a distance of at most
- * 8,640,000,000,000,000ms (100,000,000 days) from epoch (1970-01-01 UTC). In
- * other words: [:millisecondsSinceEpoch.abs() <= 8640000000000000:].
+ * See [Duration] to represent a span of time.
+ * See [Stopwatch] to measure time-spans.

[Kathy Walrath, 2013/08/19 22:06:21]

timespan is one word

(I checked http://dictionary.reference.com/browse/timespan and googled [define
timespan])

[mem, 2013/08/20 19:20:16]

Done.

+ *
+ * Create DateTime objects by using one of the constructors
+ * or by parsing a correctly formatted string.
+ * For example,

[Kathy Walrath, 2013/08/19 22:06:21]

, -> :

[mem, 2013/08/20 19:20:16]

Done.

+ *
+ *     DateTime now = new DateTime.now();
+ *     DateTime berlinWallFell = new DateTime(1989, 11, 9);
+ *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");  // 8:18pm
+ *
+ * Once created, a DateTime object cannot be changed; It has no setters.

[Kathy Walrath, 2013/08/19 22:06:21]

It -> it

[mem, 2013/08/20 19:20:16]

Done.

+ *
+ * Use getters to access

[Kathy Walrath, 2013/08/19 22:06:21]

How about just:

You can use properties to get the individual...

(Properties is what fields/ivars are called in the TOC.)

[mem, 2013/08/20 19:20:16]

Done.

+ * the individual units of a DateTime object.
+ *     assert(berlinWallFell.month == 11);
+ *     assert(moonLanding.hour == 20);
+ *
+ * For convenience and readability,
+ * the DateTime class provides a constant for each day and month name,

[Kathy Walrath, 2013/08/19 22:06:21]

name, -> name—

[mem, 2013/08/20 19:20:16]

Done.

+ * `AUGUST` and `FRIDAY` for example.

[Kathy Walrath, 2013/08/19 22:06:21]

"for example" is parenthetical and should be set off by a comma. So it should be
either:

* `AUGUST` and `FRIDAY`, for example.
*  for example, `AUGUST` and `FRIDAY`.

(I prefer the latter.)

[mem, 2013/08/20 19:20:16]

Done.

+ * You can use these with the constructors

[Kathy Walrath, 2013/08/19 22:06:21]

these -> these constants
the constructors -> constructors

[mem, 2013/08/20 19:20:16]

Done.

+ * or other places in your code where needed:

[Kathy Walrath, 2013/08/19 22:06:21]

"where needed" is unhelpful and seems formal. Maybe just drop everything after
"constructors".

[mem, 2013/08/20 19:20:16]

Done.

[mem, 2013/08/20 19:20:16]

Done.

+ *
+ *     DateTime berlinWallFell = new DateTime(1989, DateTime.NOVEMBER, 9);
+ *     assert(berlinWallFell.month == DateTime.SATURDAY);
+ *
+ * Day and month values begin at 1 and the week starts on Monday.

[Kathy Walrath, 2013/08/19 22:06:21]

 and -> , and

[mem, 2013/08/20 19:20:16]

Done.

+ * That is, the constants `JANUARY` and `MONDAY` are both 1.
+ *
+ * ## Working with time zones
+ *
+ * The DateTime class provides support for handling time zones.
+ * One constructor allows you to create a DateTime object specified
+ * in the UTC (Universal Time Coordinated) time zone.
+ * UTC is the based on the 0° longitude meridian,
+ * also known as the Greenwich meridian.
+ *
+ *     DateTime dDay = new DateTime.utc(1944, 6, 6);
+ *    
+ * Use the methods `toLocal()` and `toUtc()` to convert between UTC and local time.

[Kathy Walrath, 2013/08/19 22:06:21]

line length > 80 chars?

(this happens a bunch of times)

[mem, 2013/08/20 19:20:16]

Done.

+ * `isUtc()` indicates whether a DateTime object is based in UTC.
+ * To discover the name of the time zone use `timeZoneName()`
+ * and to find out the difference between UTC and the time zone of a DateTime object

[Kathy Walrath, 2013/08/19 22:06:21]

Split this into its own sentence.

` and to -> `. To 

[mem, 2013/08/20 19:20:16]

Done.

+ * call `timeZoneOffset()`.
+ *
+ * ## Comparing DateTime objects
+ *
+ * The DateTime class contains several handy methods,
+ * such as `isAfter()`, `isBefore()`, and `isAtSameMomentAs()`,

[Kathy Walrath, 2013/08/19 22:06:21]

should these be [blah] instead, so they'll be links?

(globally)

[mem, 2013/08/20 19:20:16]

Done.

+ * for comparing DateTime objects.
+ *
+ *     assert(berlinWallFell.isAfter(moonLanding) == true);
+ *     assert(berlinWallFell.isBefore(moonLanding) == false);
+ *
+ * ## Using DateTime with Duration
+ *
+ * Use the `add()` and `subtract()` methods in conjunction with a [Duration] object

[Kathy Walrath, 2013/08/19 22:06:21]

in conjunction with -> with

[mem, 2013/08/20 19:20:16]

Done.

+ * to create new DateTime objects based on another.
+ * For example, to find the date that is sixty days after today, write:
+ *     DateTime today = new DateTime.now();
+ *     DateTime sixtyDaysFromNow = today.add(new Duration(days: 60));
+ *
+ * To find out how much time is between two DateTime objects use
+ * `difference()`, which returns a Duration object:
+ *     Duration difference = berlinWallFell.difference(dDay);
+ *     assert(difference.inDays == 16592);
+ *
+ *
+ * ## Other resources
+ *
+ * See [Duration] to represent a span of time.
+ * See [Stopwatch] to measure time-spans.
+ *
+ * The DateTime class does not provide internationalization.
+ * Use the [intl](http://pub.dartlang.org/packages/intl) package

[Kathy Walrath, 2013/08/19 22:06:21]

Use -> To internationalize your code, use

[mem, 2013/08/20 19:20:16]

Done.

+ * at the pub shared packages repo.

[Kathy Walrath, 2013/08/19 22:06:21]

delete this line?

[mem, 2013/08/20 19:20:16]

Done.

  *
- * Also see [Stopwatch] for means to measure time-spans.
  */
+
 class DateTime implements Comparable {
   // Weekday constants that are returned by [weekday] method:
   static const int MONDAY = 1;
@@ -40,24 +114,38 @@ class DateTime implements Comparable {
   static const int MONTHS_PER_YEAR = 12;
 
   /**
-   * The milliseconds since 1970-01-01T00:00:00Z (UTC). This value is
-   * independent of the time zone.
+   * The number of milliseconds since the "Unix epoch" 1970-01-01T00:00:00Z (UTC).
+   * This value is independent of the time zone.
+   *
+   * This value is at most
+   * 8,640,000,000,000,000ms (100,000,000 days) from the Unix epoch.
+   * In other words: [:millisecondsSinceEpoch.abs() <= 8640000000000000:].
    *
-   * See [Stopwatch] for means to measure time-spans.
    */
   final int millisecondsSinceEpoch;
 
   /**
    * True if this [DateTime] is set to UTC time.
+   *
+   *     DateTime dDay = new DateTime.utc(1944, 6, 6);
+   *     assert(dDay.isUtc());

[Kathy Walrath, 2013/08/19 22:06:21]

remove ()

[mem, 2013/08/20 19:20:16]

Done.

+   *
    */
   final bool isUtc;
 
   /**
-   * Constructs a [DateTime] instance based on the individual parts. The date is
-   * in the local time zone.
+   * Constructs a [DateTime] instance based on the individual units.
+   * The date is in the local time zone.
+   * To create a new DateTime object representing July 20, 1969, 8:18pm:
    *
-   * [month] and [day] are one-based. For example
+   *     DateTime moonLanding = new DateTime(1969, DateTime.JULY, 20, 20, 18);
+   *
+   * [month] and [day] are one-based.
+   * For example,
    * [:new DateTime(1938, 1, 10):] represents the 10th of January 1938.
+   * Use the declared constants,
+   * such as `DateTime.JANUARY`, for clarity and to avoid errors.
+   * The value of [hour] is between 0 and 23, as in a 24-hour clock.

[Kathy Walrath, 2013/08/19 22:06:21]

This duplicates info that's already in the class description:

* moon landing example
* one-based
* discussion of declared constants

[mem, 2013/08/20 19:20:16]

Done.

    */
   // TODO(8042): This should be a redirecting constructor and not a factory.
   factory DateTime(int year,
@@ -72,12 +160,18 @@ class DateTime implements Comparable {
   }
 
   /**
-   * Constructs a [DateTime] instance based on the individual parts. The date is
-   * in the UTC time zone.
+   * Constructs a [DateTime] instance based on the individual units.
+   * The date is in the UTC time zone.
+   *
+   *     DateTime dDay = new DateTime.utc(1944, DateTime.JUNE, 6);
    *
-   * [month] and [day] are one-based. For example
-   * [:new DateTime.utc(1938, 1, 10):] represents the 10th of January 1938 in
+   * [month] and [day] are one-based.
+   * For example,
+   * [:new DateTime(1938, 1, 10):] represents the 10th of January 1938
    * Coordinated Universal Time.

[Kathy Walrath, 2013/08/19 22:06:21]

-> UTC

[mem, 2013/08/20 19:20:16]

Done.

+   * Use the declared constants,
+   * such as `DateTime.JANUARY`, for clarity and to avoid errors.
+   * The value of [hour] is between 0 and 23, as in a 24-hour clock.

[Kathy Walrath, 2013/08/19 22:06:21]

Could this be pulled out into the class description?

[mem, 2013/08/20 19:20:16]

Done.

    */
   // TODO(8042): This should be a redirecting constructor and not a factory.
   factory DateTime.utc(int year,
@@ -92,8 +186,11 @@ class DateTime implements Comparable {
   }
 
   /**
-   * Constructs a new [DateTime] instance with current date time value in the
+   * Constructs a [DateTime] instance with current date and time in the
    * local time zone.
+   *
+   *     DateTime thisInstant = new DateTime.now();
+   *
    */
   // TODO(8042): This should be a redirecting constructor and not a factory.
   factory DateTime.now() { return new DateTime._now(); }
@@ -163,7 +260,7 @@ class DateTime implements Comparable {
    * If [isUtc] is false then the date is in the local time zone.
    *
    * The constructed [DateTime] represents
-   * 1970-01-01T00:00:00Z + [millisecondsSinceEpoch]ms in the given
+   * 1970-01-01T00:00:00Z + [millisecondsSinceEpoch] ms in the given
    * time zone (local or UTC).
    */
   // TODO(lrn): Have two constructors instead of taking an optional bool.
@@ -181,6 +278,11 @@ class DateTime implements Comparable {
    * Returns true if [other] is a [DateTime] at the same moment and in the
    * same timezone (UTC or local).
    *
+   *     DateTime dDayUtc   = new DateTime.utc(1944, DateTime.JUNE, 6);
+   *     DateTime dDayLocal = new DateTime(1944, DateTime.JUNE, 6);
+   *
+   *     assert(dDayUtc.isAtSameMomentAs(dDayLocal) == false);
+   *
    * See [isAtSameMomentAs] for a comparison that ignores the timezone.
    */
   bool operator ==(other) {
@@ -192,6 +294,12 @@ class DateTime implements Comparable {
   /**
    * Returns true if [this] occurs before [other]. The comparison is independent

[Kathy Walrath, 2013/08/19 22:06:21]

Make the first paragraph one sentence long.

I don't know what "is independent of" means. Does that mean it takes the time
zone into account, or not?

[mem, 2013/08/20 19:20:16]

I'm leaving this for now. Not sure what to say instead.

On 2013/08/19 22:06:21, Kathy Walrath wrote:

    * of whether the time is in UTC or in the local time zone.
+   *
+   *     DateTime berlinWallFell = new DateTime(1989, 11, 9);
+   *     DateTime moonLanding    = DateTime.parse("1969-07-20 20:18:00");
+   *
+   *     assert(berlinWallFell.isBefore(moonLanding) == false);
+   *
    */
   bool isBefore(DateTime other) {
     return millisecondsSinceEpoch < other.millisecondsSinceEpoch;
@@ -200,6 +308,12 @@ class DateTime implements Comparable {
   /**
    * Returns true if [this] occurs after [other]. The comparison is independent

[Kathy Walrath, 2013/08/19 22:06:21]

See comment for isBefore().

    * of whether the time is in UTC or in the local time zone.
+   *
+   *     DateTime berlinWallFell = new DateTime(1989, 11, 9);
+   *     DateTime moonLanding    = DateTime.parse("1969-07-20 20:18:00");
+   *
+   *     assert(berlinWallFell.isAfter(moonLanding) == true);
+   *
    */
   bool isAfter(DateTime other) {
     return millisecondsSinceEpoch > other.millisecondsSinceEpoch;
@@ -209,19 +323,33 @@ class DateTime implements Comparable {
    * Returns true if [this] occurs at the same moment as [other]. The

[Kathy Walrath, 2013/08/19 22:06:21]

See comment for isBefore().

    * comparison is independent of whether the time is in UTC or in the local
    * time zone.
+   *
+   *     DateTime berlinWallFell = new DateTime(1989, 11, 9);
+   *     DateTime moonLanding    = DateTime.parse("1969-07-20 20:18:00");
+   *
+   *     assert(berlinWallFell.isAtSameMomentAs(moonLanding) == false);
    */
   bool isAtSameMomentAs(DateTime other) {
     return millisecondsSinceEpoch == other.millisecondsSinceEpoch;
   }
 
+  /**
+   * Compares this DateTime object to [other].
+   * Returns:

[Kathy Walrath, 2013/08/19 22:06:21]

Should be in a separate paragraph.
I'm not crazy about the construction of this, especially the punctuation at the
ends of each bulleted item.

[mem, 2013/08/20 19:20:16]

Done.

+   *
+   * * a negative integer if this DateTime is smaller (earlier) than [other],
+   * * zero if this DateTime is equal to [other], or
+   * * a positive integer if this DateTime is greater (later) than [other].
+   */
+
   int compareTo(DateTime other)
       => millisecondsSinceEpoch.compareTo(other.millisecondsSinceEpoch);
 
   int get hashCode => millisecondsSinceEpoch;
 
   /**
-   * Returns [this] in the local time zone. Returns itself if it is already in
-   * the local time zone. Otherwise, this method is equivalent to
+   * Returns [this] if it is already in the local time zone.

[Kathy Walrath, 2013/08/19 22:06:21]

convert this first paragraph into a single sentence

[mem, 2013/08/20 19:20:16]

Done.

+   * Otherwise, this method is equivalent to:
    *
    *     new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
    *                                             isUtc: false)
@@ -235,8 +363,8 @@ class DateTime implements Comparable {
   }
 
   /**
-   * Returns [this] in UTC. Returns itself if it is already in UTC. Otherwise,
-   * this method is equivalent to
+   * Returns [this] if it is already in UTC.

[Kathy Walrath, 2013/08/19 22:06:21]

convert this first paragraph into a single sentence

[mem, 2013/08/20 19:20:16]

Done.

+   * Otherwise, this method is equivalent to:
    *
    *     new DateTime.fromMillisecondsSinceEpoch(millisecondsSinceEpoch,
    *                                             isUtc: true)
@@ -248,8 +376,12 @@ class DateTime implements Comparable {
   }
 
   /**
-   * Returns a human readable string for this instance.
+   * Returns a human-readable string for this instance.

[Kathy Walrath, 2013/08/19 22:06:21]

add a blank line after this one.

[mem, 2013/08/20 19:20:16]

Done.

    * The returned string is constructed for the time zone of this instance.
+   * The `toString()` method provides a simply formatted string.
+   * It does not support internationalized strings.
+   * Use the [intl](http://pub.dartlang.org/packages/intl) package
+   * at the pub shared packages repo.
    */
   String toString() {
     String fourDigits(int n) {
@@ -286,21 +418,41 @@ class DateTime implements Comparable {
     }
   }
 
-  /** Returns a new [DateTime] with the [duration] added to [this]. */
+  /**
+   * Returns a new [DateTime] instance with [duration] added to [this].
+   *
+   *     DateTime today = new DateTime.now();
+   *     DateTime sixtyDaysFromNow = today.add(new Duration(days: 60));
+   */
+
   DateTime add(Duration duration) {
     int ms = millisecondsSinceEpoch;
     return new DateTime.fromMillisecondsSinceEpoch(
         ms + duration.inMilliseconds, isUtc: isUtc);
   }
 
-  /** Returns a new [DateTime] with the [duration] subtracted from [this]. */
+  /**
+   * Returns a new [DateTime] instance with [duration] subtracted from [this].
+   *
+   *     DateTime today = new DateTime.now();
+   *     DateTime sixtyDaysAgo = today.subtract(new Duration(days: 60));
+   */
   DateTime subtract(Duration duration) {
     int ms = millisecondsSinceEpoch;
     return new DateTime.fromMillisecondsSinceEpoch(
         ms - duration.inMilliseconds, isUtc: isUtc);
   }
 
-  /** Returns a [Duration] with the difference of [this] and [other]. */
+  /**
+   * Returns a [Duration] with the difference between [this] and [other].
+   *
+   *     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);
+   */
+
   Duration difference(DateTime other) {
     int ms = millisecondsSinceEpoch;
     int otherMs = other.millisecondsSinceEpoch;
@@ -321,9 +473,7 @@ class DateTime implements Comparable {
       int millisecond, bool isUtc);
 
   /**
-   * Returns the abbreviated time-zone name.
-   *
-   * Examples: [:"CET":] or [:"CEST":].
+   * Returns the abbreviated time-zone name. For example: [:"CET":] or [:"CEST":].

[Kathy Walrath, 2013/08/19 22:06:21]

convert this first paragraph into a single sentence

[mem, 2013/08/20 19:20:16]

Done.

[mem, 2013/08/20 19:20:16]

Done.

    */
   external String get timeZoneName;
 
@@ -339,42 +489,69 @@ class DateTime implements Comparable {
 
   /**
    * Returns the year.
+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.year == 1969);
    */
   external int get year;
 
   /**
    * Returns the month into the year [1..12].

[Kathy Walrath, 2013/08/19 22:06:21]

into -> of

[mem, 2013/08/20 19:20:16]

Done.

+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.month == 7);
+   *     assert(moonLanding.month == JULY);
    */
   external int get month;
 
   /**
    * Returns the day into the month [1..31].

[Kathy Walrath, 2013/08/19 22:06:21]

into -> of

[mem, 2013/08/20 19:20:16]

Done.

+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.day == 20);
    */
   external int get day;
 
   /**
    * Returns the hour into the day [0..23].

[Kathy Walrath, 2013/08/19 22:06:21]

into -> of

[mem, 2013/08/20 19:20:16]

Done.

+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.hour == 20);
    */
   external int get hour;
 
   /**
    * Returns the minute into the hour [0...59].

[Kathy Walrath, 2013/08/19 22:06:21]

into -> of

[mem, 2013/08/20 19:20:16]

Done.

+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.minute == 18);
    */
   external int get minute;
 
   /**
    * Returns the second into the minute [0...59].

[Kathy Walrath, 2013/08/19 22:06:21]

into -> of

[mem, 2013/08/20 19:20:16]

Done.

+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.second == 0);
    */
   external int get second;
 
   /**
    * Returns the millisecond into the second [0...999].

[Kathy Walrath, 2013/08/19 22:06:21]

into -> of?

After a while, "into/of the xyz" just starts to look weird to me.

+   *
+   *     DateTime moonLanding = DateTime.parse("1969-07-20 20:18:00");
+   *     assert(moonLanding.millisecond == 0);
    */
   external int get millisecond;
 
   /**
    * Returns the week day [MON..SUN]. In accordance with ISO 8601

[Kathy Walrath, 2013/08/19 22:06:21]

week day -> day of the week

Put a blank line before "In".

 which -> , which

[mem, 2013/08/20 19:20:16]

Done.

    * 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;
 }