Improve conversion docstrings (#453)

src/conversions.jl

@@ -8,13 +8,20 @@ const utc_tz = FixedTimeZone("UTC")
 """
     DateTime(zdt::ZonedDateTime) -> DateTime
 
-Create a `DateTime` by dropping the associated time zone. Effectively, this new `DateTime`
-is implicitly associated with `timezone(zdt)`.
+Construct a `DateTime` based on the "local time" representation of the provided
+`ZonedDateTime`.
+
+!!! warning
+
+    Any arithmetic performed on the returned `DateTime` will be timezone unaware and will
+    not reflect an accurate local time if the operation would cross a DST transition.
+
+See also: [`DateTime(::ZonedDateTime, ::Type{UTC})`](@ref).
 
 # Example
 
 ```jldoctest
-julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4")
+julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York")
 2014-05-30T21:00:00-04:00
 
 julia> DateTime(zdt)
@@ -26,12 +33,14 @@ Dates.DateTime(zdt::ZonedDateTime) = zdt.utc_datetime + zdt.zone.offset
 """
     DateTime(zdt::ZonedDateTime, ::Type{UTC}) -> DateTime
 
-Create a `DateTime` which is implicitly associated with UTC.
+Construct a `DateTime` based on the UTC representation of the provided `ZonedDateTime`.
+
+See also: [`DateTime(::ZonedDateTime)`](@ref).
 
 # Example
 
 ```jldoctest
-julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4")
+julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York")
 2014-05-30T21:00:00-04:00
 
 julia> DateTime(zdt, UTC)
@@ -44,13 +53,14 @@ Dates.DateTime(zdt::ZonedDateTime, ::Type{UTC}) = zdt.utc_datetime
 """
     Date(zdt::ZonedDateTime) -> Date
 
-Create a `Date` by dropping the associated time zone. Effectively, this new `Date`
-is implicitly associated with `timezone(zdt)`.
+Construct a `Date` based on the "local time" representation of the provided `ZonedDateTime`.
+
+See also: [`Date(::ZonedDateTime, ::Type{UTC})`](@ref).
 
 # Example
 
 ```jldoctest
-julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4")
+julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York")
 2014-05-30T21:00:00-04:00
 
 julia> Date(zdt)
@@ -63,12 +73,14 @@ Dates.Date(zdt::ZonedDateTime) = Date(DateTime(zdt))
 """
     Date(zdt::ZonedDateTime, ::Type{UTC}) -> Date
 
-Create a `Date` which is implicitly associated with UTC.
+Construct a `Date` based on the UTC representation of the provided `ZonedDateTime`.
+
+See also: [`Date(::ZonedDateTime)`](@ref).
 
 # Example
 
 ```jldoctest
-julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4")
+julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York")
 2014-05-30T21:00:00-04:00
 
 julia> Date(zdt, UTC)
@@ -81,13 +93,14 @@ Dates.Date(zdt::ZonedDateTime, ::Type{UTC}) = Date(DateTime(zdt, UTC))
 """
     Time(zdt::ZonedDateTime) -> Time
 
-Create a `Time` by dropping the associated time zone. Effectively, this new `Time`
-is implicitly associated with `timezone(zdt)`.
+Construct a `Time` based on the "local time" representation of the provided `ZonedDateTime`.
+
+See also: [`Time(::ZonedDateTime, ::Type{UTC})`](@ref).
 
 # Example
 
 ```jldoctest
-julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4")
+julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York")
 2014-05-30T21:00:00-04:00
 
 julia> Time(zdt)
@@ -100,12 +113,14 @@ Dates.Time(zdt::ZonedDateTime) = Time(DateTime(zdt))
 """
     Time(zdt::ZonedDateTime, ::Type{UTC}) -> Date
 
-Create a `Time` which is implicitly associated with UTC.
+Construct a `Time` based on the UTC representation of the provided `ZonedDateTime`.
+
+See also: [`Time(::ZonedDateTime)`](@ref).
 
 # Example
 
 ```jldoctest
-julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4")
+julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York")
 2014-05-30T21:00:00-04:00
 
 julia> Time(zdt, UTC)
@@ -118,7 +133,9 @@ Dates.Time(zdt::ZonedDateTime, ::Type{UTC}) = Time(DateTime(zdt, UTC))
 """
     now(::TimeZone) -> ZonedDateTime
 
-Returns a `ZonedDateTime` corresponding to the user's system time in the specified `TimeZone`.
+Create a `ZonedDateTime` corresponding to the current system time in the specified `TimeZone`.
+
+See also: [`today(::TimeZone)`](@ref), [`todayat(::TimeZone)`](@ref).
 """
 function Dates.now(tz::TimeZone)
     utc = unix2datetime(time())
@@ -128,7 +145,9 @@ end
 """
     today(tz::TimeZone) -> Date
 
-Returns the date portion of `now(tz)` in local time.
+Create the current `Date` in the specified `TimeZone`. Equivalent to `Date(now(tz))`.
+
+See also: [`now(::TimeZone)`](@ref), [`todayat(::TimeZone)`](@ref).
 
 # Examples
 
@@ -146,19 +165,30 @@ julia> today(tz"Pacific/Midway"), today(tz"Pacific/Apia")
 Dates.today(tz::TimeZone) = Date(now(tz))
 
 """
-    todayat(tod::Time, tz::TimeZone, [amb]) -> ZonedDateTime
+    todayat(tod::Time, tz::TimeZone, [amb::Union{Integer,Bool}]) -> ZonedDateTime
 
 Creates a `ZonedDateTime` for today at the specified time of day. If the result is ambiguous
 in the given `TimeZone` then `amb` can be supplied to resolve ambiguity.
 
+See also: [`now(::TimeZone)`](@ref), [`today(::TimeZone)`](@ref).
+
 # Examples
 
 ```julia
 julia> today(tz"Europe/Warsaw")
-2017-11-09
+2017-10-29
 
 julia> todayat(Time(10, 30), tz"Europe/Warsaw")
-2017-11-09T10:30:00+01:00
+2017-10-29T10:30:00+01:00
+
+julia> todayat(Time(2), tz"Europe/Warsaw")
+ERROR: AmbiguousTimeError: Local DateTime 2017-10-29T02:00:00 is ambiguous within Europe/Warsaw
+
+julia> todayat(Time(2), tz"Europe/Warsaw", 1)
+2017-10-29T02:00:00+02:00
+
+julia> todayat(Time(2), tz"Europe/Warsaw", 2)
+2017-10-29T02:00:00+01:00
 ```
 """
 function todayat(tod::Time, tz::VariableTimeZone, amb::Union{Integer,Bool})