fix Date Functions docs references; refresh doco for

Author: mtd321

stdlib/Dates/docs/src/index.md

@@ -4,8 +4,10 @@
 DocTestSetup = :(using Dates)
 ```
 
-The `Dates` module provides two types for working with dates: [`Date`](@ref) and [`DateTime`](@ref),
-representing day and millisecond precision, respectively; both are subtypes of the abstract [`TimeType`](@ref).
+The `Dates` module provides three types for representing dates and times:
+[`Date`](@ref), [`DateTime`](@ref), and [`Time`](@ref) representing
+day, millisecond and nanosecond precision, respectively;
+all are subtypes of the abstract [`TimeType`](@ref).
 The motivation for distinct types is simple: some operations are much simpler, both in terms of
 code and mental reasoning, when the complexities of greater precision don't have to be dealt with.
 For example, since the [`Date`](@ref) type only resolves to the precision of a single date (i.e.
@@ -14,7 +16,7 @@ time, and leap seconds are unnecessary and avoided.
 
 Both [`Date`](@ref) and [`DateTime`](@ref) are basically immutable [`Int64`](@ref) wrappers.
 The single `instant` field of either type is actually a `UTInstant{P}` type, which
-represents a continuously increasing machine timeline based on the UT second [^1]. The
+represents a monotonically increasing machine timeline based on the UT second [^1]. The
 [`DateTime`](@ref) type is not aware of time zones (*naive*, in Python parlance),
 analogous to a *LocalDateTime* in Java 8. Additional time zone functionality
 can be added through the [TimeZones.jl package](https://github.com/JuliaTime/TimeZones.jl/), which
@@ -26,6 +28,10 @@ The ISO standard, however, states that 1 BC/BCE is year zero, so `0000-12-31` is
 `0001-01-01`, and year `-0001` (yes, negative one for the year) is 2 BC/BCE, year `-0002` is 3
 BC/BCE, etc.
 
+The [`Time`](@ref) is also an immutable [`Int64`](@ref) wrapper, also based on the UT second [^1],
+but constrained to represent the periodic (cyclic) time of the 24-hour day starting at midnight.
+Note that midnight is represented as 0 hour - 24 hour is out of range.
+
 [^1]:
     The notion of the UT second is actually quite fundamental. There are basically two different notions
     of time generally accepted, one based on the physical rotation of the earth (one full rotation
@@ -457,6 +463,18 @@ julia> collect(dr)
  2014-05-29
  2014-06-29
  2014-07-29
+
+julia> r = range(Time(0), step = Hour(9), length = 5)
+Time(0):Hour(9):Time(12)
+
+julia> collect(r)
+5-element Vector{Time}:
+ 00:00:00
+ 09:00:00
+ 18:00:00
+ 03:00:00
+ 12:00:00
+
 ```
 
 ## Adjuster Functions
@@ -707,7 +725,7 @@ Dates.UTC
 Dates.DateTime(::Int64, ::Int64, ::Int64, ::Int64, ::Int64, ::Int64, ::Int64)
 Dates.DateTime(::Dates.Period)
 Dates.DateTime(::Function, ::Any...)
-Dates.DateTime(::Dates.TimeType)
+Dates.DateTime(::Dates.Date)
 Dates.DateTime(::AbstractString, ::AbstractString)
 Dates.format(::Dates.TimeType, ::AbstractString)
 Dates.DateFormat
@@ -716,7 +734,7 @@ Dates.DateTime(::AbstractString, ::Dates.DateFormat)
 Dates.Date(::Int64, ::Int64, ::Int64)
 Dates.Date(::Dates.Period)
 Dates.Date(::Function, ::Any, ::Any, ::Any)
-Dates.Date(::Dates.TimeType)
+Dates.Date(::Dates.DateTime)
 Dates.Date(::AbstractString, ::AbstractString)
 Dates.Date(::AbstractString, ::Dates.DateFormat)
 Dates.Time(::Int64::Int64, ::Int64, ::Int64, ::Int64, ::Int64)

stdlib/Dates/src/types.jl

@@ -132,7 +132,7 @@ struct UTC <: TimeZone end
 """
     TimeType
 
-`TimeType` types wrap `Instant` machine instances to provide human representations of the
+`TimeType` types wrap `Instant` machine instants to provide human representations of the
 machine instant. `Time`, `DateTime` and `Date` are subtypes of `TimeType`.
 """
 abstract type TimeType <: AbstractTime end