std.datetime: document DST handling

[dlangBugzillaToGithub]

dhasenan (@dhasenan) reported this on 2015-11-15T07:03:09Z

Transfered from https://issues.dlang.org/show_bug.cgi?id=15339

Description

DateTime (specifically TimeOfDay) contains validation to ensure that its hour is never above 23. This means that it is intended to represent time shown on a typical clock (and not, for instance, the nth hour of the day). This should be documented.

When daylight saving time starts and ends, there is a day with fewer or more than 24 hours. In the US, the hour of 2am is repeated or omitted as appropriate. This results in ambiguous dates. This should be documented.

Since `SysTime(DateTime(2015, 11, 1, 1, 0, 0), TimeZone.getTimeZone("America/Los Angeles")).add!"hours"(1)` returns 2015-11-01T01:00:00, it should further be documented (after verification) that the date chosen is the earlier of applicable dates.

It should further be clarified that `SysTime(DateTime(2015, 11, 1, 1, 0, 0), TimeZone.getTimeZone("America/Los Angeles")).add!"hours"(1).add!"hours"(1)` does in fact yield 2015-11-01T02:00:00, as you would expect.

Finally, we should add unittests to ensure we don't break this behavior.