Hi Dave, all of the Timespans are instantiated as positions by default
(e.g., ignoring timezone), which is the common case.  If/when someone
might need a Date, Month, Week, etc. which begins at a
timezone-specific time, they will be glad to see that it is handled
automatically.  For example, when adding a Timespan to a DateAndTime
with the #+ message, the result gets the same offset as the receiver.

But this uncommon case is revealed at method-level code and comments,
so I would just simplify the class comment to:

    Instances of Date are Timespans with duration of 1 day.

Oh, i like that.  It reflects the simplicity and elegance of
Chronology's implementation which is able to interoperate with itself.

Best,
  Chris



> Would the following work as a class comment for Date?
>
>   Date provides methods for dealing with calendar dates in different formats.
>
>   Instances of Date are Timespans with duration of 1 day beginning at midnight.
>   The start value of midnight, and possibly the duration of 1 day, depend on
>   the time zone in which the Date is defined.
>
>   In the most common usage, a Date is defined relative to UTC (time zone offset
>   zero), and thus may be treated as a location independent calendar value.
>
>   The current date, Date today, is assumed to be defined as a UTC date without
>   consideration of local time zone.
>
>
> Dave
>
>
> On Sun, Jun 26, 2016 at 11:30:35PM -0400, David T. Lewis wrote:
>> Hi Chris,
>>
>> I was really just trying to ask for a good class comment. The current
>> comment contains an error, and I used that as an excuse for raising the
>> question.
>>
>> I want to know the *meaning* of the Date class. And I would like the
>> class comment to say what it means. The meaning seems to have changed
>> considerably over the last ten or fifteen years as the implementations
>> have changed, and I think that it would be helpful if the current
>> definition could be stated as clearly as possible.
>>
>>
>> On Sat, Jun 25, 2016 at 07:34:02PM -0500, Chris Muller wrote:
>> > Hi Dave, Dates created as positions by default is the definitely the
>> > correct behavior.  The original Date implementation inherited the
>> > abstraction from Timespan of a custom duration starting at a
>> > particular DateAndTime.  While that is a fine for abstract Timespans,
>> > it turned out to be a bad idea for Dates, since the vast majority of
>> > the use of Dates are as positions, not spans.
>>
>> I am not sure what is meant by "Dates as positions". When I first read
>> this, I was thinking of "position relative to GMT" but on reading it
>> again I realized that it probably means "position on a continuum of date
>> values". Or maybe I am just completely confused (hence my plea for a
>> good class comment). Despite my confusion, my own best guess at the
>> current intended meaning of "Date" was in my original question below.
>>
>> A bit off topic, but is is worth asking:
>> If we really want to model Date as a position on a continuum of date
>> values, and if we think that the implementation of Date as a kind of
>> Timespan is not right, then shouldn't we just consider going back to
>> the earlier (Squeak 3.6 and earlier) implementation of Date as a Magnitude,
>> rather than Date as a Timespan?
>>
>> Dave
>>
>> >
>> > Check out the discussion surrounding Berts recent clarification of the
>> > implementation, where the timezone for Dates-as-positions is now set
>> > to nil, so the "localized" or "globalized" nomenclature can be removed
>> > from the comment.
>> >
>> >  - Chris
>> >
>> >
>> > On Thu, Jun 23, 2016 at 8:05 AM, David T. Lewis <lewis at mail.msen.com> wrote:
>> > > 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
>> > >
>> > >
>