On Tue, Jun 28, 2016 at 08:18:53PM -0400, David T. Lewis wrote:
> On Tue, Jun 28, 2016 at 01:41:28PM -0500, Chris Muller wrote:
> > 
> > > I was really just trying to ask for a good class comment.
> > 
> > I really do think this is the best way to do this clarification.  Did
> > you notice that Bert already updated the class comment of Timespan to
> > mention the dual capability?  So, I think simply removing that old
> > stuff from Date's comment is simple and effective solution without
> > breaking legacy apps.
> 
> This was my attempt at 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.
> 
> Alternative attempts welcome :-)
> 
> Dave
>

Chris, thanks for updating the class comment for Date. Summarizing where we are now:

Brent's original class comment is:

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

And our class comment (Chronology-Core-cmm.6.mcz) is:

  Instances of Date are Timespans with duration of 1 day.  As with all Chronology
  Timespan sub-instances, Dates can be instantiated as position values which
  compare equally to any other instance of the same Date, irregardless of the
  timezone in which either is created.

  However, like the other Timespan subInstances, there are rare cases where it
  may be desirable to use instances of Date to represent a particular 1-day
  span of time at a particular locality on the globe.  All Timespans, including
  Dates, may specify a particular timezone offset for this purpose.

It seems that Brent's intent was to represent a date starting at midnight in
the local time zone. For various reasons, we now treat it more like a magnitude,
representing it as a one day duration beginning at midnight UTC. That works
better for most actual usage of class Date, but it does leave me thinking that
we are mashing up two different concepts.

To be clear, I am not planning to actually /do/ anything about this, I am just
trying to clarify the documentation and my own understanding. It might well be
a good idea to have two different classes to represent date as duration versus
date as magnitude, but I certainly have no intention of taking that on until we
decide to use or discard the UTCDateAndTime updates that I previously proposed.

My primary motiviation is to make sure that the changes in UTCDateAndTime pass
the unit tests while also respecting the design intent. So I am not trying to
be a pain in the ass, I am really trying to understand the intended meaning of
the class, and I am trying to reconcile Brent's original intent with the various
changes that we have made since its introduction.

Thanks :-)

Dave