Merge pull request #501 from chronotope/check-docs

Check that documentation builds without warnings on nightly

.github/workflows/test.yml

@@ -132,3 +132,18 @@ jobs:
 
       - name: Build static library
         run: cross check --target ${{ matrix.target }}
+
+  check-docs:
+    runs-on: ubuntu-latest
+    name: Check doc links
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install rust nightly
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: nightly
+          override: true
+      - name: Check docs build without warnings
+        env:
+          RUSTDOCFLAGS: '-D warnings'
+        run: cargo +nightly doc

src/date.rs

@@ -290,7 +290,7 @@ where
     }
 
     /// Formats the date with the specified format string.
-    /// See the [`format::strftime` module](./format/strftime/index.html)
+    /// See the [`::format::strftime`] module
     /// on the supported escape sequences.
     #[cfg(any(feature = "alloc", feature = "std", test))]
     #[inline]
@@ -320,7 +320,7 @@ where
     }
 
     /// Formats the date with the specified format string and locale.
-    /// See the [`format::strftime` module](./format/strftime/index.html)
+    /// See the [`::format::strftime`] module
     /// on the supported escape sequences.
     #[cfg(feature = "unstable-locales")]
     #[inline]

src/datetime.rs

@@ -332,7 +332,7 @@ where
 
 impl DateTime<FixedOffset> {
     /// Parses an RFC 2822 date and time string such as `Tue, 1 Jul 2003 10:52:37 +0200`,
-    /// then returns a new `DateTime` with a parsed `FixedOffset`.
+    /// then returns a new [`DateTime`] with a parsed [`FixedOffset`].
     ///
     /// RFC 2822 is the internet message standard that specifices the
     /// representation of times in HTTP and email headers.
@@ -352,7 +352,7 @@ impl DateTime<FixedOffset> {
     }
 
     /// Parses an RFC 3339 and ISO 8601 date and time string such as `1996-12-19T16:39:57-08:00`,
-    /// then returns a new `DateTime` with a parsed `FixedOffset`.
+    /// then returns a new [`DateTime`] with a parsed [`FixedOffset`].
     ///
     /// Why isn't this named `parse_from_iso8601`? That's because ISO 8601 allows some freedom
     /// over the syntax and RFC 3339 exercises that freedom to rigidly define a fixed format.
@@ -363,15 +363,17 @@ impl DateTime<FixedOffset> {
         parsed.to_datetime()
     }
 
-    /// Parses a string with the specified format string and
+    /// Parses a string with the specified format string and returns a new
-    /// returns a new `DateTime` with a parsed `FixedOffset`.
+    /// [`DateTime`] with a parsed [`FixedOffset`].
-    /// See the [`format::strftime` module](./format/strftime/index.html)
-    /// on the supported escape sequences.
     ///
-    /// See also `Offset::datetime_from_str` which gives a local `DateTime` on specific time zone.
+    /// See the [`::format::strftime`] module on the supported escape
+    /// sequences.
+    ///
+    /// See also [`TimeZone::datetime_from_str`] which gives a local
+    /// [`DateTime`] on specific time zone.
     ///
     /// Note that this method *requires a timezone* in the string. See
-    /// [`NaiveDateTime::parse_from_str`](./naive/struct.NaiveDateTime.html#method.parse_from_str)
+    /// [`NaiveDateTime::parse_from_str`]
     /// for a version that does not require a timezone in the to-be-parsed str.
     ///
     /// # Example
@@ -409,11 +411,11 @@ where
     }
 
     /// Return an RFC 3339 and ISO 8601 date and time string with subseconds
-    /// formatted as per a `SecondsFormat`. If passed `use_z` true and the
+    /// formatted as per a `SecondsFormat`.
-    /// timezone is UTC (offset 0), use 'Z', as per
+    ///
-    /// [Fixed::TimezoneOffsetColonZ](format/enum.Fixed.html#variant.TimezoneOffsetColonZ).
+    /// If passed `use_z` true and the timezone is UTC (offset 0), use 'Z', as
-    /// If passed `use_z` false, use
+    /// per [`Fixed::TimezoneOffsetColonZ`] If passed `use_z` false, use
-    /// [Fixed::TimezoneOffsetColon](format/enum.Fixed.html#variant.TimezoneOffsetColon).
+    /// [`Fixed::TimezoneOffsetColon`]
     ///
     /// # Examples
     ///
@@ -488,7 +490,7 @@ where
     }
 
     /// Formats the combined date and time with the specified format string.
-    /// See the [`format::strftime` module](./format/strftime/index.html)
+    /// See the [`::format::strftime`] module
     /// on the supported escape sequences.
     #[cfg(any(feature = "alloc", feature = "std", test))]
     #[inline]
@@ -518,9 +520,11 @@ where
         )
     }
 
-    /// Formats the combined date and time with the specified format string and locale.
+    /// Formats the combined date and time with the specified format string and
-    /// See the [`format::strftime` module](./format/strftime/index.html)
+    /// locale.
-    /// on the supported escape sequences.
+    ///
+    /// See the [`::format::strftime`] module on the supported escape
+    /// sequences.
     #[cfg(feature = "unstable-locales")]
     #[inline]
     pub fn format_localized<'a>(
@@ -1005,7 +1009,7 @@ pub mod rustc_serialize {
         }
     }
 
-    /// A `DateTime` that can be deserialized from a timestamp
+    /// A [`DateTime`] that can be deserialized from a timestamp
     ///
     /// A timestamp here is seconds since the epoch
     #[derive(Debug)]
@@ -1200,7 +1204,7 @@ pub mod serde {
             serializer.serialize_i64(dt.timestamp_nanos())
         }
 
-        /// Deserialize a `DateTime` from a nanosecond timestamp
+        /// Deserialize a [`DateTime`] from a nanosecond timestamp
         ///
         /// Intended for use with `serde`s `deserialize_with` attribute.
         ///

src/lib.rs

@@ -425,9 +425,10 @@
     // becomes 1.17, should be able to remove this, those 'static lifetimes,
     // and use `static` in a lot of places `const` is used now.
     redundant_static_lifetimes,
-    // Similarly, redundant_field_names lints on not using the
+    // the field-init shorthand (which this lint recommends) was stabilized in rust 1.17.
-    // field-init-shorthand, which was stabilized in rust 1.17.
     redundant_field_names,
+    // `matches!` was stabilized in 1.42
+    match_like_matches_macro,
     // Changing trivially_copy_pass_by_ref would require an incompatible version
     // bump.
     trivially_copy_pass_by_ref,

src/naive/datetime.rs

@@ -702,7 +702,7 @@ impl NaiveDateTime {
 impl Datelike for NaiveDateTime {
     /// Returns the year number in the [calendar date](./index.html#calendar-date).
     ///
-    /// See also the [`NaiveDate::year`](./struct.NaiveDate.html#method.year) method.
+    /// See also the [`NaiveDate::year`] method.
     ///
     /// # Example
     ///
@@ -857,8 +857,7 @@ impl Datelike for NaiveDateTime {
     ///
     /// Returns `None` when the resulting `NaiveDateTime` would be invalid.
     ///
-    /// See also the
+    /// See also the [`NaiveDate::with_year`] method.
-    /// [`NaiveDate::with_year`](./struct.NaiveDate.html#method.with_year) method.
     ///
     /// # Example
     ///
@@ -878,8 +877,7 @@ impl Datelike for NaiveDateTime {
     ///
     /// Returns `None` when the resulting `NaiveDateTime` would be invalid.
     ///
-    /// See also the
+    /// See also the [`NaiveDate::with_month`] method.
-    /// [`NaiveDate::with_month`](./struct.NaiveDate.html#method.with_month) method.
     ///
     /// # Example
     ///
@@ -900,8 +898,7 @@ impl Datelike for NaiveDateTime {
     ///
     /// Returns `None` when the resulting `NaiveDateTime` would be invalid.
     ///
-    /// See also the
+    /// See also the [`NaiveDate::with_month0`] method.
-    /// [`NaiveDate::with_month0`](./struct.NaiveDate.html#method.with_month0) method.
     ///
     /// # Example
     ///
@@ -922,8 +919,7 @@ impl Datelike for NaiveDateTime {
     ///
     /// Returns `None` when the resulting `NaiveDateTime` would be invalid.
     ///
-    /// See also the
+    /// See also the [`NaiveDate::with_day`] method.
-    /// [`NaiveDate::with_day`](./struct.NaiveDate.html#method.with_day) method.
     ///
     /// # Example
     ///
@@ -943,8 +939,7 @@ impl Datelike for NaiveDateTime {
     ///
     /// Returns `None` when the resulting `NaiveDateTime` would be invalid.
     ///
-    /// See also the
+    /// See also the [`NaiveDate::with_day0`] method.
-    /// [`NaiveDate::with_day0`](./struct.NaiveDate.html#method.with_day0) method.
     ///
     /// # Example
     ///
@@ -964,8 +959,7 @@ impl Datelike for NaiveDateTime {
     ///
     /// Returns `None` when the resulting `NaiveDateTime` would be invalid.
     ///
-    /// See also the
+    /// See also the [`NaiveDate::with_ordinal`] method.
-    /// [`NaiveDate::with_ordinal`](./struct.NaiveDate.html#method.with_ordinal) method.
     ///
     /// # Example
     ///
@@ -992,8 +986,7 @@ impl Datelike for NaiveDateTime {
     ///
     /// Returns `None` when the resulting `NaiveDateTime` would be invalid.
     ///
-    /// See also the
+    /// See also the [`NaiveDate::with_ordinal0`] method.
-    /// [`NaiveDate::with_ordinal0`](./struct.NaiveDate.html#method.with_ordinal0) method.
     ///
     /// # Example
     ///
@@ -1020,7 +1013,7 @@ impl Datelike for NaiveDateTime {
 impl Timelike for NaiveDateTime {
     /// Returns the hour number from 0 to 23.
     ///
-    /// See also the [`NaiveTime::hour`](./struct.NaiveTime.html#method.hour) method.
+    /// See also the [`NaiveTime::hour`] method.
     ///
     /// # Example
     ///
@@ -1037,7 +1030,7 @@ impl Timelike for NaiveDateTime {
 
     /// Returns the minute number from 0 to 59.
     ///
-    /// See also the [`NaiveTime::minute`](./struct.NaiveTime.html#method.minute) method.
+    /// See also the [`NaiveTime::minute`] method.
     ///
     /// # Example
     ///
@@ -1054,7 +1047,7 @@ impl Timelike for NaiveDateTime {
 
     /// Returns the second number from 0 to 59.
     ///
-    /// See also the [`NaiveTime::second`](./struct.NaiveTime.html#method.second) method.
+    /// See also the [`NaiveTime::second`] method.
     ///
     /// # Example
     ///
@@ -1073,8 +1066,7 @@ impl Timelike for NaiveDateTime {
     /// The range from 1,000,000,000 to 1,999,999,999 represents
     /// the [leap second](./struct.NaiveTime.html#leap-second-handling).
     ///
-    /// See also the
+    /// See also the [`NaiveTime::nanosecond`] method.
-    /// [`NaiveTime::nanosecond`](./struct.NaiveTime.html#method.nanosecond) method.
     ///
     /// # Example
     ///
@@ -1093,8 +1085,7 @@ impl Timelike for NaiveDateTime {
     ///
     /// Returns `None` when the resulting `NaiveDateTime` would be invalid.
     ///
-    /// See also the
+    /// See also the [`NaiveTime::with_hour`] method.
-    /// [`NaiveTime::with_hour`](./struct.NaiveTime.html#method.with_hour) method.
     ///
     /// # Example
     ///
@@ -1116,7 +1107,7 @@ impl Timelike for NaiveDateTime {
     /// Returns `None` when the resulting `NaiveDateTime` would be invalid.
     ///
     /// See also the
-    /// [`NaiveTime::with_minute`](./struct.NaiveTime.html#method.with_minute) method.
+    /// [`NaiveTime::with_minute`] method.
     ///
     /// # Example
     ///
@@ -1135,12 +1126,11 @@ impl Timelike for NaiveDateTime {
 
     /// Makes a new `NaiveDateTime` with the second number changed.
     ///
-    /// Returns `None` when the resulting `NaiveDateTime` would be invalid.
+    /// Returns `None` when the resulting `NaiveDateTime` would be invalid. As
-    /// As with the [`second`](#method.second) method,
+    /// with the [`NaiveDateTime::second`] method, the input range is
-    /// the input range is restricted to 0 through 59.
+    /// restricted to 0 through 59.
     ///
-    /// See also the
+    /// See also the [`NaiveTime::with_second`] method.
-    /// [`NaiveTime::with_second`](./struct.NaiveTime.html#method.with_second) method.
     ///
     /// # Example
     ///
@@ -1160,12 +1150,10 @@ impl Timelike for NaiveDateTime {
     /// Makes a new `NaiveDateTime` with nanoseconds since the whole non-leap second changed.
     ///
     /// Returns `None` when the resulting `NaiveDateTime` would be invalid.
-    /// As with the [`nanosecond`](#method.nanosecond) method,
+    /// As with the [`NaiveDateTime::nanosecond`] method,
     /// the input range can exceed 1,000,000,000 for leap seconds.
     ///
-    /// See also the
+    /// See also the [`NaiveTime::with_nanosecond`] method.
-    /// [`NaiveTime::with_nanosecond`](./struct.NaiveTime.html#method.with_nanosecond)
-    /// method.
     ///
     /// # Example
     ///
@@ -1203,8 +1191,8 @@ impl hash::Hash for NaiveDateTime {
 /// except when the `NaiveDateTime` itself represents a leap second
 /// in which case the assumption becomes that **there is exactly a single leap second ever**.
 ///
-/// Panics on underflow or overflow.
+/// Panics on underflow or overflow. Use [`NaiveDateTime::checked_add_signed`]
-/// Use [`NaiveDateTime::checked_add_signed`](#method.checked_add_signed) to detect that.
+/// to detect that.
 ///
 /// # Example
 ///
@@ -1273,8 +1261,8 @@ impl AddAssign<OldDuration> for NaiveDateTime {
 /// except when the `NaiveDateTime` itself represents a leap second
 /// in which case the assumption becomes that **there is exactly a single leap second ever**.
 ///
-/// Panics on underflow or overflow.
+/// Panics on underflow or overflow. Use [`NaiveDateTime::checked_sub_signed`]
-/// Use [`NaiveDateTime::checked_sub_signed`](#method.checked_sub_signed) to detect that.
+/// to detect that.
 ///
 /// # Example
 ///
@@ -1342,8 +1330,7 @@ impl SubAssign<OldDuration> for NaiveDateTime {
 /// in which case the assumption becomes that
 /// **there are exactly one (or two) leap second(s) ever**.
 ///
-/// The implementation is a wrapper around
+/// The implementation is a wrapper around [`NaiveDateTime::signed_duration_since`].
-/// [`NaiveDateTime::signed_duration_since`](#method.signed_duration_since).
 ///
 /// # Example
 ///
@@ -1363,8 +1350,8 @@ impl SubAssign<OldDuration> for NaiveDateTime {
 /// # }
 /// ~~~~
 ///
-/// Leap seconds are handled, but the subtraction assumes that
+/// Leap seconds are handled, but the subtraction assumes that no other leap
-/// there were no other leap seconds happened.
+/// seconds happened.
 ///
 /// ~~~~
 /// # extern crate chrono; fn main() {
@@ -1387,7 +1374,7 @@ impl Sub<NaiveDateTime> for NaiveDateTime {
 }
 
 /// The `Debug` output of the naive date and time `dt` is the same as
-/// [`dt.format("%Y-%m-%dT%H:%M:%S%.f")`](../format/strftime/index.html).
+/// [`dt.format("%Y-%m-%dT%H:%M:%S%.f")`](::format::strftime).
 ///
 /// The string printed can be readily parsed via the `parse` method on `str`.
 ///
@@ -1420,7 +1407,7 @@ impl fmt::Debug for NaiveDateTime {
 }
 
 /// The `Display` output of the naive date and time `dt` is the same as
-/// [`dt.format("%Y-%m-%d %H:%M:%S%.f")`](../format/strftime/index.html).
+/// [`dt.format("%Y-%m-%d %H:%M:%S%.f")`](::format::strftime).
 ///
 /// It should be noted that, for leap seconds not on the minute boundary,
 /// it may print a representation not distinguishable from non-leap seconds.
@@ -1451,7 +1438,7 @@ impl fmt::Display for NaiveDateTime {
 }
 
 /// Parsing a `str` into a `NaiveDateTime` uses the same format,
-/// [`%Y-%m-%dT%H:%M:%S%.f`](../format/strftime/index.html), as in `Debug`.
+/// [`%Y-%m-%dT%H:%M:%S%.f`](::format::strftime), as in `Debug`.
 ///
 /// # Example
 ///

src/offset/mod.rs

@@ -403,16 +403,17 @@ pub trait TimeZone: Sized + Clone {
         self.timestamp_opt(secs, nanos as u32).unwrap()
     }
 
-    /// Parses a string with the specified format string and
+    /// Parses a string with the specified format string and returns a
-    /// returns a `DateTime` with the current offset.
+    /// `DateTime` with the current offset.
-    /// See the [`format::strftime` module](../format/strftime/index.html)
-    /// on the supported escape sequences.
     ///
-    /// If the format does not include offsets, the current offset is assumed;
+    /// See the [`::format::strftime`] module on the
-    /// otherwise the input should have a matching UTC offset.
+    /// supported escape sequences.
     ///
-    /// See also `DateTime::parse_from_str` which gives a local `DateTime`
+    /// If the to-be-parsed string includes an offset, it *must* match the
-    /// with parsed `FixedOffset`.
+    /// offset of the TimeZone, otherwise an error will be returned.
+    ///
+    /// See also [`DateTime::parse_from_str`] which gives a [`DateTime`] with
+    /// parsed [`FixedOffset`].
     fn datetime_from_str(&self, s: &str, fmt: &str) -> ParseResult<DateTime<Self>> {
         let mut parsed = Parsed::new();
         parse(&mut parsed, s, StrftimeItems::new(fmt))?;