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