The class comment says:

  Instances of Date are Timespans with duration of 1 day.

  Their default creation assumes a start of midnight of UTC to provide the fast, globalized Dates out of the box.  The legacy behavior that creates Timezone-sensitive Dates can be used by sending #localizedDates.


I no longer see #localizedDates in the image, so I think the comment needs an update.


For reference, and earlier version of the class comment said this:

  Instances of Date are Timespans with duration of 1 day.
  Their default creation assumes a start of midnight in the local time zone.


I am not sure what the comment should say, but I would be happy if it could
better convey the intended meaning of "Date" in addition to the explanation
about creating instances relative to UTC versus local time zone.

My expectation would be that a Date is a Timespan with a start value set to
midnight in some time zone. The start value is a DateAndTime, and the offset
instance variable of that DateAndTime would reflect that time zone.

I would therefore expect that a "globalized" Date is a special case of a Date
that was created with the start of the Timespan at midnight UTC, regardless
of the current local time zone. A "globalized" Date is no different from any
other Date, it is simply a Date that was created with time zone UTC.

Is that right?

Dave