Push more prominently for folks to use NaiveDate over Date

src/date.rs

@@ -21,24 +21,31 @@ use {Datelike, Weekday};
 
 /// ISO 8601 calendar date with time zone.
 ///
-/// This type should be considered ambiguous at best,
+/// You almost certainly want to be using a [`NaiveDate`] instead of this type.
-/// due to the inherent lack of precision required for the time zone resolution.
+///
-/// For serialization and deserialization uses, it is best to use `NaiveDate` instead.
+/// This type primarily exists to aid in the construction of DateTimes that
+/// have a timezone by way of the [`TimeZone`] datelike constructors (e.g.
+/// [`TimeZone::ymd`]).
+///
+/// This type should be considered ambiguous at best, due to the inherent lack
+/// of precision required for the time zone resolution.
+///
 /// There are some guarantees on the usage of `Date<Tz>`:
 ///
-/// - If properly constructed via `TimeZone::ymd` and others without an error,
+/// - If properly constructed via [`TimeZone::ymd`] and others without an error,
 ///   the corresponding local date should exist for at least a moment.
 ///   (It may still have a gap from the offset changes.)
 ///
-/// - The `TimeZone` is free to assign *any* `Offset` to the local date,
+/// - The `TimeZone` is free to assign *any* [`Offset`](::offset::Offset) to the
-///   as long as that offset did occur in given day.
+///   local date, as long as that offset did occur in given day.
+///
 ///   For example, if `2015-03-08T01:59-08:00` is followed by `2015-03-08T03:00-07:00`,
 ///   it may produce either `2015-03-08-08:00` or `2015-03-08-07:00`
 ///   but *not* `2015-03-08+00:00` and others.
 ///
-/// - Once constructed as a full `DateTime`,
+/// - Once constructed as a full `DateTime`, [`DateTime::date`] and other associated
-///   `DateTime::date` and other associated methods should return those for the original `Date`.
+///   methods should return those for the original `Date`. For example, if `dt =
-///   For example, if `dt = tz.ymd(y,m,d).hms(h,n,s)` were valid, `dt.date() == tz.ymd(y,m,d)`.
+///   tz.ymd(y,m,d).hms(h,n,s)` were valid, `dt.date() == tz.ymd(y,m,d)`.
 ///
 /// - The date is timezone-agnostic up to one day (i.e. practically always),
 ///   so the local date and UTC date should be equal for most cases

src/datetime.rs

@@ -23,7 +23,7 @@ use format::DelayedFormat;
 use format::Locale;
 use format::{parse, ParseError, ParseResult, Parsed, StrftimeItems};
 use format::{Fixed, Item};
-use naive::{self, IsoWeek, NaiveDateTime, NaiveTime};
+use naive::{self, IsoWeek, NaiveDate, NaiveDateTime, NaiveTime};
 #[cfg(feature = "clock")]
 use offset::Local;
 use offset::{FixedOffset, Offset, TimeZone, Utc};
@@ -96,12 +96,45 @@ impl<Tz: TimeZone> DateTime<Tz> {
         DateTime { datetime: datetime, offset: offset }
     }
 
-    /// Retrieves a date component.
+    /// Retrieves a date component
+    ///
+    /// Unless you are immediately planning on turning this into a `DateTime`
+    /// with the same Timezone you should use the
+    /// [`date_naive`](DateTime::date_naive) method.
+    ///
+    /// ```
+    /// use chrono::prelude::*;
+    ///
+    /// let date: Date<Utc> = Utc.ymd(2020, 1, 1);
+    /// let dt: DateTime<Utc> = date.and_hms(0, 0, 0);
+    ///
+    /// assert_eq!(dt.date(), date);
+    ///
+    /// assert_eq!(dt.date().and_hms(1, 1, 1), date.and_hms(1, 1, 1));
+    /// ```
     #[inline]
     pub fn date(&self) -> Date<Tz> {
         Date::from_utc(self.naive_local().date(), self.offset.clone())
     }
 
+    /// Retrieves the Date without an associated timezone
+    ///
+    /// [`NaiveDate`] is a more well-defined type, and has more traits implemented on it,
+    /// so should be preferred to [`Date`] any time you truly want to operate on Dates.
+    ///
+    /// ```
+    /// use chrono::prelude::*;
+    ///
+    /// let date: DateTime<Utc> = Utc.ymd(2020, 1, 1).and_hms(0, 0, 0);
+    /// let other: DateTime<FixedOffset> = FixedOffset::east(23).ymd(2020, 1, 1).and_hms(0, 0, 0);
+    /// assert_eq!(date.date_naive(), other.date_naive());
+    /// ```
+    #[inline]
+    pub fn date_naive(&self) -> NaiveDate {
+        let local = self.naive_local();
+        NaiveDate::from_ymd(local.year(), local.month(), local.day())
+    }
+
     /// Retrieves a time component.
     /// Unlike `date`, this is not associated to the time zone.
     #[inline]