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