Create documentation for Dates.format

- Added documentation for Dates.format
- Added documentation for date accessors
- Eliminated cross-referencing similar to: "see above"
- Sync date accessor docstrings with manual
- Fixed signatures of certain Period constructors. Hour, Minute, Second
  and Millisecond would always fail when a Date was given as an argument

base/dates/accessors.jl

@@ -71,3 +71,68 @@ yearmonthday(dt::TimeType) = yearmonthday(days(dt))
 @vectorize_1arg TimeType yearmonth
 @vectorize_1arg TimeType monthday
 @vectorize_1arg TimeType yearmonthday
+
+
+# Documentation for exported accessors
+for func in (:year, :month)
+    name = string(func)
+    @eval begin
+        @doc """
+            $($name)(dt::TimeType) -> Int64
+
+        The $($name) of a `Date` or `DateTime` as an `Int64`.
+        """ $func(dt::TimeType)
+    end
+end
+
+"""
+    week(dt::TimeType) -> Int64
+
+Return the [ISO week date](https://en.wikipedia.org/wiki/ISO_week_date) of a `Date` or
+`DateTime` as an `Int64`. Note that the first week of a year is the week that contains the
+first Thursday of the year which can result in dates prior to January 4th being in the last
+week of the previous year. For example `week(Date(2005,1,1))` is the 53rd week of 2004.
+"""
+week(dt::TimeType)
+
+for func in (:day, :dayofmonth)
+    name = string(func)
+    @eval begin
+        @doc """
+            $($name)(dt::TimeType) -> Int64
+
+        The day of month of a `Date` or `DateTime` as an `Int64`.
+        """ $func(dt::TimeType)
+    end
+end
+
+"""
+    hour(dt::DateTime) -> Int64
+
+The hour of day of a `DateTime` as an `Int64`.
+"""
+hour(dt::DateTime)
+
+for func in (:minute, :second, :millisecond)
+    name = string(func)
+    @eval begin
+        @doc """
+            $($name)(dt::DateTime) -> Int64
+
+        The $($name) of a `DateTime` as an `Int64`.
+        """ $func(dt::DateTime)
+    end
+end
+
+for parts in (["year", "month"], ["month", "day"], ["year", "month", "day"])
+    name = join(parts)
+    func = symbol(name)
+    @eval begin
+        @doc """
+            $($name)(dt::TimeType) -> ($(join(repeated(Int64, length($parts)), ", ")))
+
+        Simultaneously return the $(join($parts, ", ", " and ")) parts of a `Date` or
+        `DateTime`.
+        """ $func(dt::TimeType)
+    end
+end

base/dates/io.jl

@@ -82,7 +82,7 @@ SLOT_RULE['s'] = Millisecond
 
 duplicates(slots) = any(map(x->count(y->x.parser==y.parser,slots),slots) .> 1)
 
-function DateFormat(f::AbstractString,locale::AbstractString="english")
+function DateFormat(f::AbstractString, locale::AbstractString="english")
     slots = Slot[]
     prefix = ""
     params = ()

base/dates/periods.jl

@@ -6,15 +6,34 @@ value(x::Period) = x.value
 # The default constructors for Periods work well in almost all cases
 # P(x) = new((convert(Int64,x))
 # The following definitions are for Period-specific safety
-for p in (:Year,:Month,:Week,:Day,:Hour,:Minute,:Second,:Millisecond)
+for period in (:Year, :Month, :Week, :Day, :Hour, :Minute, :Second, :Millisecond)
+    period_str = string(period)
+    accessor_str = lowercase(period_str)
     # Convenience method for show()
-    @eval _units(x::$p) = $(" " * lowercase(string(p))) * (abs(value(x)) == 1 ? "" : "s")
+    @eval _units(x::$period) = " " * $accessor_str * (abs(value(x)) == 1 ? "" : "s")
     # periodisless
-    @eval periodisless(x::$p,y::$p) = value(x) < value(y)
+    @eval periodisless(x::$period,y::$period) = value(x) < value(y)
     # AbstractString parsing (mainly for IO code)
-    @eval $p(x::AbstractString) = $p(Base.parse(Int64,x))
+    @eval $period(x::AbstractString) = $period(Base.parse(Int64,x))
     # Period accessors
-    @eval $p(x::TimeType) = $p($(symbol(lowercase(string(p))))(x))
+    typ_str = period in (:Hour, :Minute, :Second, :Millisecond) ? "DateTime" : "TimeType"
+    description = typ_str == "TimeType" ? "`Date` or `DateTime`" : "`$typ_str`"
+    reference = period == :Week ? " For details see [`$accessor_str(::$typ_str)`](:func:`$accessor_str`)." : ""
+    @eval begin
+        @doc """
+            $($period_str)(dt::$($typ_str)) -> $($period_str)
+
+        The $($accessor_str) part of a $($description) as a `$($period_str)`.$($reference)
+        """ ->
+        $period(dt::$(symbol(typ_str))) = $period($(symbol(accessor_str))(dt))
+
+        @doc """
+            $($period_str)(v)
+
+        Construct a `$($period_str)` object with the given `v` value. Input must be
+        losslessly convertible to an `Int64`.
+        """ $period(v)
+    end
 end
 # Now we're safe to define Period-Number conversions
 # Anything an Int64 can convert to, a Period can convert to

base/docs/helpdb.jl

@@ -11306,11 +11306,50 @@ So a ``dt`` string of "1996-01-15T00:00:00.0" would have a ``format`` string lik
 """
 Dates.DateTime(dt::AbstractString, format::AbstractString)
 
+doc"""
+```rst
+..  format(dt::TimeType, format::AbstractString; locale="english") -> AbstractString
+
+Construct a string by using a ``TimeType`` object and applying the provided ``format``. The
+following character codes can be used to construct the ``format`` string:
+
+=============== ========= ===============================================================
+Code            Examples  Comment
+=============== ========= ===============================================================
+``y``           6         Numeric year with a fixed width
+``m``           1, 12     Numeric month with a minimum width
+``u``           Jan       Month name shortened to 3-chars according to the ``locale``
+``U``           January   Full month name according to the ``locale`` keyword
+``d``           0, 23     Hour (24-hour clock) with a minimum width
+``H``           0, 59     Minute with a minimum width
+``M``           0, 59     Second with a minimum width
+``S``           000, 500  Millisecond with a minimum width of 3
+``s``           .500      Matches milliseconds
+``e``           Mon, Tue  Abbreviated days of the week
+``E``           Monday    Full day of week name
+=============== ========= ===============================================================
+
+The number of sequential code characters indicate the width of the code. A format of
+``yyyy-mm`` specifies that the code ``y`` should have a width of four while ``m`` a width of
+two. Codes that yield numeric digits have an associated mode: fixed-width or minimum-width.
+The fixed-width mode left-pads the value with zeros when it is shorter than the specified
+width and truncates the value when longer. Minimum-width mode works the same as fixed-width
+except that it does not truncate values longer than the width.
+
+When creating a ``format`` you can use any non-code characters as a separator. For example to
+generate the string "1996-01-15T00:00:00" you could use ``format``: "yyyy-mm-ddTHH:MM:SS".
+```
+"""
+Dates.format(dt::AbstractString, format::AbstractString)
+
 doc"""
 ```rst
 ..  DateTime(dt::AbstractString, df::DateFormat) -> DateTime
 
-Similar form as above for parsing a ``DateTime``, but passes a ``DateFormat`` object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create a ``DateFormat`` object then use this method for parsing.
+Construct a ``DateTime`` by parsing the ``dt`` date string following the pattern given in
+the :func:`Dates.DateFormat` object. Similar to
+``DateTime(::AbstractString, ::AbstractString)`` but more efficient when repeatedly parsing
+similarly formatted date strings with a pre-created ``DateFormat`` object.
 ```
 """
 Dates.DateTime(dt::AbstractString, df::Dates.DateFormat)
@@ -11367,7 +11406,9 @@ Dates.Date(dt::DateTime)
 doc"""
     Date(dt::AbstractString, format::AbstractString; locale="english") -> Date
 
-Construct a `Date` type by parsing a `dt` date string following the pattern given in the `format` string. Follows the same conventions as `DateTime` above.
+Construct a `Date` object by parsing a `dt` date string following the pattern given in the
+`format` string. Follows the same conventions as
+`DateTime(::AbstractString, ::AbstractString)`.
 """
 Dates.Date(dt::AbstractString, format::AbstractString)
 
@@ -11430,20 +11471,6 @@ Takes the number of Julian calendar days since epoch
 """
 Dates.julian2datetime
 
-doc"""
-    year(dt::TimeType) -> Int64
-    month(dt::TimeType) -> Int64
-    week(dt::TimeType) -> Int64
-    day(dt::TimeType) -> Int64
-    hour(dt::TimeType) -> Int64
-    minute(dt::TimeType) -> Int64
-    second(dt::TimeType) -> Int64
-    millisecond(dt::TimeType) -> Int64
-
-Return the field part of a `Date` or `DateTime` as an `Int64`.
-"""
-Dates.year
-
 doc"""
     toprev(dt::TimeType,dow::Int;same::Bool=false) -> TimeType
 
@@ -11482,13 +11509,6 @@ Returns the number of days in the month of `dt`. Value will be 28, 29, 30, or 31
 """
 Dates.daysinmonth
 
-doc"""
-    yearmonth(dt::TimeType) -> (Int64, Int64)
-
-Simultaneously return the year and month parts of a `Date` or `DateTime`.
-"""
-Dates.yearmonth
-
 doc"""
     daysofweekinmonth(dt::TimeType) -> Int
 
@@ -11497,18 +11517,15 @@ For the day of week of `dt`, returns the total number of that day of the week in
 Dates.daysofweekinmonth
 
 doc"""
-    yearmonthday(dt::TimeType) -> (Int64, Int64, Int64)
-
-Simultaneously return the year, month, and day parts of a `Date` or `DateTime`.
-"""
-Dates.yearmonthday
-
-doc"""
-    Dates.DateFormat(format::AbstractString) -> DateFormat
+```rst
+..  DateFormat(format::AbstractString, locale::AbstractString="english") -> DateFormat
 
-Construct a date formatting object that can be passed repeatedly for parsing similarly formatted date strings. `format` is a format string in the form described above (e.g. `"yyyy-mm-dd"`).
+Construct a date formatting object that can be used for parsing date strings or
+formatting a date object as a string. For details on the syntax for ``format`` see
+:ref:`parsing <man-date-parsing>` and :ref:`formatting <man-date-formatting>`.
+```
 """
-Dates.Dates.DateFormat
+Dates.DateFormat
 
 doc"""
     lastdayofweek(dt::TimeType) -> TimeType
@@ -11524,13 +11541,6 @@ doc"""
 """
 Dates.recur
 
-doc"""
-    monthday(dt::TimeType) -> (Int64, Int64)
-
-Simultaneously return the month and day parts of a `Date` or `DateTime`.
-"""
-Dates.monthday
-
 doc"""
     default(p::Period) -> Period
 
@@ -11629,35 +11639,6 @@ Returns the day of the week as an `Int64` with `1 = Monday, 2 = Tuesday, etc.`.
 """
 Dates.dayofweek
 
-doc"""
-    Year(dt::TimeType) -> Year
-    Month(dt::TimeType) -> Month
-    Week(dt::TimeType) -> Week
-    Day(dt::TimeType) -> Day
-    Hour(dt::TimeType) -> Hour
-    Minute(dt::TimeType) -> Minute
-    Second(dt::TimeType) -> Second
-    Millisecond(dt::TimeType) -> Millisecond
-
-Return the field part of a `Date` or `DateTime` as a `Period` type.
-"""
-Dates.Year(dt::Dates.TimeType)
-
-doc"""
-    Year(v)
-    Month(v)
-    Week(v)
-    Day(v)
-    Hour(v)
-    Minute(v)
-    Second(v)
-    Millisecond(v)
-
-Construct a `Period` type with the given `v` value. Input must be losslessly
-convertible to an `Int64`.
-"""
-Dates.Year(v)
-
 doc"""
     quarterofyear(dt::TimeType) -> Int