From 7081354f36e91c0ec81b818be756eb6a19d55356 Mon Sep 17 00:00:00 2001
From: jch8ri <jachh1094@gmail.com>
Date: Mon, 6 May 2019 16:25:48 -0400
Subject: [PATCH] updated some docs for issue #31202

---
 stdlib/Dates/src/Dates.jl |  3 ++-
 stdlib/Dates/src/io.jl    | 40 +++++++++++++++++++++++++++++++++++++++
 stdlib/Dates/src/types.jl |  1 +
 3 files changed, 43 insertions(+), 1 deletion(-)

diff --git a/stdlib/Dates/src/Dates.jl b/stdlib/Dates/src/Dates.jl
index 8e30d352e830f..31df18a4a53b6 100644
--- a/stdlib/Dates/src/Dates.jl
+++ b/stdlib/Dates/src/Dates.jl
@@ -50,7 +50,8 @@ include("io.jl")
 include("parse.jl")
 include("deprecated.jl")
 
-export Period, DatePeriod, TimePeriod,
+export #types.jl
+       Period, DatePeriod, TimePeriod,
        Year, Month, Week, Day, Hour, Minute, Second, Millisecond,
        Microsecond, Nanosecond,
        TimeZone, UTC, TimeType, DateTime, Date, Time,
diff --git a/stdlib/Dates/src/io.jl b/stdlib/Dates/src/io.jl
index e1cf80394dd7f..87d0b0b11586b 100644
--- a/stdlib/Dates/src/io.jl
+++ b/stdlib/Dates/src/io.jl
@@ -393,9 +393,49 @@ macro dateformat_str(str)
 end
 
 # Standard formats
+
+#ISO8601 'DateTime' Format for 'date' and 'time' formatting. Default Format.
+#Example
+'''
+jldoctest
+
+julia> Dates.ISODateTimeFormat
+dateformat"yyyy-mm-ddTHH:MM:SS.s"
+
+julia> Dates.format(Dates.now(), Dates.ISODateFormat)
+"2019-04-15T17:18:05.439"
+
+'''
 const ISODateTimeFormat = DateFormat("yyyy-mm-dd\\THH:MM:SS.s")
+
+#ISO8601 'Date' Format for 'date' formatting.
+#Example
+'''
+jldoctest
+
+julia> Dates.format(Dates.today(), Dates.ISODateFormat)
+"2019-04-15"
+'''
 const ISODateFormat = DateFormat("yyyy-mm-dd")
+
+#Default ISO8601 Time Format for time formatting.
+#Example
+'''
+jldoctest
+
+julia> Dates.format(Dates.Time(Dates.now()), ISOTimeFormat)
+"17:22:01.292"
+'''
 const ISOTimeFormat = DateFormat("HH:MM:SS.s")
+
+#Traditional RFC1123 Format for date/time formatting.
+#Example
+'''
+jldoctest
+
+julia> Dates.format(Dates.now(), RFC1123Format)
+"Mon, 15 Apr 2019 17:26:57"
+'''
 const RFC1123Format = DateFormat("e, dd u yyyy HH:MM:SS")
 
 default_format(::Type{DateTime}) = ISODateTimeFormat
diff --git a/stdlib/Dates/src/types.jl b/stdlib/Dates/src/types.jl
index ee3255a116313..0f5ca83900c40 100644
--- a/stdlib/Dates/src/types.jl
+++ b/stdlib/Dates/src/types.jl
@@ -83,6 +83,7 @@ abstract type Calendar <: AbstractTime end
 # ISOCalendar provides interpretation rules for UTInstants to civil date and time parts
 struct ISOCalendar <: Calendar end
 
+#Time Zones in ISO 8601 are represented as an offset from UTC
 abstract type TimeZone end
 struct UTC <: TimeZone end