Update documentation

src/date.rs

@@ -243,8 +243,6 @@ impl Date {
 
     /// Get the month.
     ///
-    /// The returned value will always be in the range `1..=12`.
-    ///
     /// ```rust
     /// # use time::{macros::date, Month};
     /// assert_eq!(date!(2019 - 01 - 01).month(), Month::January);
@@ -658,9 +656,7 @@ impl Date {
 #[cfg(feature = "formatting")]
 #[cfg_attr(__time_03_docs, doc(cfg(feature = "formatting")))]
 impl Date {
-    /// Format the `Date` using the provided format description. The formatted value will be output
-    /// to the provided writer. The format description will typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Format the `Date` using the provided [format description](crate::format_description).
     pub fn format_into(
         self,
         output: &mut impl io::Write,
@@ -669,9 +665,7 @@ impl Date {
         format.format_into(output, Some(self), None, None)
     }
 
-    /// Format the `Date` using the provided format description. The format description will
-    /// typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Format the `Date` using the provided [format description](crate::format_description).
     ///
     /// ```rust
     /// # use time::{format_description, macros::date};
@@ -687,9 +681,8 @@ impl Date {
 #[cfg(feature = "parsing")]
 #[cfg_attr(__time_03_docs, doc(cfg(feature = "parsing")))]
 impl Date {
-    /// Parse a `Date` from the input using the provided format description. The format description
-    /// will typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Parse a `Date` from the input using the provided [format
+    /// description](crate::format_description).
     ///
     /// ```rust
     /// # use time::{format_description, macros::date, Date};

src/error/mod.rs

@@ -33,7 +33,7 @@ pub use try_from_parsed::TryFromParsed;
 /// A unified error type for anything returned by a method in the time crate.
 ///
 /// This can be used when you either don't know or don't care about the exact error returned.
-/// `Result<_, time::Error>` will work in these situations.
+/// `Result<_, time::Error>` (or its alias `time::Result<_>`) will work in these situations.
 #[allow(missing_copy_implementations, variant_size_differences)]
 #[allow(clippy::missing_docs_in_private_items)] // variants only
 #[non_exhaustive]

src/ext.rs

@@ -12,10 +12,7 @@ mod sealed {
 }
 
 // region: NumericalDuration
-/// Create [`Duration`]s from primitive and core numeric types.
-///
-/// Due to limitations in rustc, these methods are currently _not_ `const fn`. See
-/// [RFC 2632](https://github.com/rust-lang/rfcs/pull/2632) for details.
+/// Create [`Duration`]s from numeric literals.
 ///
 /// # Examples
 ///
@@ -147,10 +144,7 @@ impl NumericalDuration for f64 {
 // endregion NumericalDuration
 
 // region: NumericalStdDuration
-/// Create [`std::time::Duration`]s from primitive and core numeric types.
-///
-/// Due to limitations in rustc, these methods are currently _not_ `const fn`. See
-/// [RFC 2632](https://github.com/rust-lang/rfcs/pull/2632) for details.
+/// Create [`std::time::Duration`]s from numeric literals.
 ///
 /// # Examples
 ///

src/format_description/mod.rs

@@ -1,4 +1,9 @@
 //! Description of how types should be formatted and parsed.
+//!
+//! The formatted value will be output to the provided writer. Format descriptions can be
+//! [well-known](crate::format_description::well_known) or obtained by using the
+//! [`format_description!`](crate::macros::format_description) macro, the
+//! [`format_description::parse`](crate::format_description::parse()) function.
 
 mod component;
 pub mod modifier;

src/format_description/parse.rs

@@ -77,6 +77,9 @@ fn parse_item<'a>(
 }
 
 /// Parse a sequence of items from the format description.
+///
+/// The syntax for the format description can be found in [the
+/// book](https://time-rs.github.io/book/api/format-description.html).
 #[cfg_attr(__time_03_docs, doc(cfg(feature = "alloc")))]
 pub fn parse(s: &str) -> Result<Vec<FormatItem<'_>>, InvalidFormatDescription> {
     let mut compound = Vec::new();

src/lib.rs

@@ -69,7 +69,8 @@
 //! only available to end users; this is to ensure that a user doesn't have unsound behavior without
 //! knowing it. To enable this behavior, you must use `RUSTFLAGS="--cfg unsound_local_offset" cargo
 //! build` or similar. Note: This flag is _not tested anywhere_, including in the regular test of
-//! the powerset of all feature flags. Use at your own risk.
+//! the powerset of all feature flags. Use at your own risk. Without this flag, any method that
+//! requires the local offset will return the `Err` variant.
 
 #![doc(html_playground_url = "https://play.rust-lang.org")]
 #![cfg_attr(__time_03_docs, feature(doc_cfg))]

src/macros.rs

@@ -46,6 +46,9 @@ pub use time_macros::datetime;
 /// # Ok::<_, time::Error>(())
 /// ```
 ///
+/// The syntax accepted by this macro is the same as [`format_description::parse()`], which can
+/// be found in [the book](https://time-rs.github.io/book/api/format-description.html).
+///
 /// [`format_description::parse()`]: crate::format_description::parse()
 #[cfg(any(feature = "formatting", feature = "parsing"))]
 #[cfg_attr(

src/offset_date_time.rs

@@ -67,9 +67,6 @@ impl OffsetDateTime {
     /// assert!(OffsetDateTime::now_local().is_ok());
     /// # }
     /// ```
-    ///
-    /// Due to a [soundness bug](https://github.com/time-rs/time/issues/293),
-    /// the error value is currently always returned on Unix-like platforms.
     #[cfg(feature = "local-offset")]
     #[cfg_attr(__time_03_docs, doc(cfg(feature = "local-offset")))]
     pub fn now_local() -> Result<Self, error::IndeterminateOffset> {
@@ -318,8 +315,6 @@ impl OffsetDateTime {
 
     /// Get the month of the date in the stored offset.
     ///
-    /// The returned value will always be in the range `1..=12`.
-    ///
     /// ```rust
     /// # use time::Month;
     /// # use time::macros::{datetime, offset};
@@ -779,9 +774,8 @@ impl OffsetDateTime {
 #[cfg(feature = "formatting")]
 #[cfg_attr(__time_03_docs, doc(cfg(feature = "formatting")))]
 impl OffsetDateTime {
-    /// Format the `OffsetDateTime` using the provided format description. The formatted value will
-    /// be output to the provided writer. The format description will typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Format the `OffsetDateTime` using the provided [format
+    /// description](crate::format_description).
     pub fn format_into(
         self,
         output: &mut impl io::Write,
@@ -796,9 +790,8 @@ impl OffsetDateTime {
         )
     }
 
-    /// Format the `OffsetDateTime` using the provided format description. The format description
-    /// will typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Format the `OffsetDateTime` using the provided [format
+    /// description](crate::format_description).
     ///
     /// ```rust
     /// # use time::{format_description, macros::datetime};
@@ -821,9 +814,8 @@ impl OffsetDateTime {
 #[cfg(feature = "parsing")]
 #[cfg_attr(__time_03_docs, doc(cfg(feature = "parsing")))]
 impl OffsetDateTime {
-    /// Parse a `PrimitiveDateTime` from the input using the provided format description. The format
-    /// description will typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Parse an `OffsetDateTime` from the input using the provided [format
+    /// description](crate::format_description).
     ///
     /// ```rust
     /// # use time::{format_description, macros::datetime, OffsetDateTime};

src/primitive_date_time.rs

@@ -71,8 +71,6 @@ impl PrimitiveDateTime {
 
     /// Get the month of the date.
     ///
-    /// The returned value will always be in the range `1..=12`.
-    ///
     /// ```rust
     /// # use time::{macros::datetime, Month};
     /// assert_eq!(datetime!(2019-01-01 0:00).month(), Month::January);
@@ -409,7 +407,7 @@ impl PrimitiveDateTime {
         }
     }
 
-    /// Assuming that the existing `PrimitiveDateTime` represents a moment in the UTC, return an
+    /// Assuming that the existing `PrimitiveDateTime` represents a moment in UTC, return an
     /// [`OffsetDateTime`].
     ///
     /// ```rust
@@ -504,9 +502,8 @@ impl PrimitiveDateTime {
 #[cfg(feature = "formatting")]
 #[cfg_attr(__time_03_docs, doc(cfg(feature = "formatting")))]
 impl PrimitiveDateTime {
-    /// Format the `PrimitiveDateTime` using the provided format description. The formatted value
-    /// will be output to the provided writer. The format description will typically be parsed by
-    /// using [`format_description::parse`](crate::format_description::parse()).
+    /// Format the `PrimitiveDateTime` using the provided [format
+    /// description](crate::format_description).
     pub fn format_into(
         self,
         output: &mut impl io::Write,
@@ -515,9 +512,8 @@ impl PrimitiveDateTime {
         format.format_into(output, Some(self.date), Some(self.time), None)
     }
 
-    /// Format the `PrimitiveDateTime` using the provided format description. The format description
-    /// will typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Format the `PrimitiveDateTime` using the provided [format
+    /// description](crate::format_description).
     ///
     /// ```rust
     /// # use time::{format_description, macros::datetime};
@@ -536,9 +532,8 @@ impl PrimitiveDateTime {
 #[cfg(feature = "parsing")]
 #[cfg_attr(__time_03_docs, doc(cfg(feature = "parsing")))]
 impl PrimitiveDateTime {
-    /// Parse a `PrimitiveDateTime` from the input using the provided format description. The format
-    /// description will typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Parse a `PrimitiveDateTime` from the input using the provided [format
+    /// description](crate::format_description).
     ///
     /// ```rust
     /// # use time::{format_description, macros::datetime, PrimitiveDateTime};

src/time.rs

@@ -411,9 +411,7 @@ impl Time {
 #[cfg(feature = "formatting")]
 #[cfg_attr(__time_03_docs, doc(cfg(feature = "formatting")))]
 impl Time {
-    /// Format the `Time` using the provided format description. The formatted value will be output
-    /// to the provided writer. The format description will typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Format the `Time` using the provided [format description](crate::format_description).
     pub fn format_into(
         self,
         output: &mut impl io::Write,
@@ -422,9 +420,7 @@ impl Time {
         format.format_into(output, None, Some(self), None)
     }
 
-    /// Format the `Time` using the provided format description. The format description will
-    /// typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Format the `Time` using the provided [format description](crate::format_description).
     ///
     /// ```rust
     /// # use time::{format_description, macros::time};
@@ -440,9 +436,8 @@ impl Time {
 #[cfg(feature = "parsing")]
 #[cfg_attr(__time_03_docs, doc(cfg(feature = "parsing")))]
 impl Time {
-    /// Parse a `Time` from the input using the provided format description. The format description
-    /// will typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Parse a `Time` from the input using the provided [format
+    /// description](crate::format_description).
     ///
     /// ```rust
     /// # use time::{format_description, macros::time, Time};

src/utc_offset.rs

@@ -227,9 +227,6 @@ impl UtcOffset {
     /// assert!(local_offset.is_ok());
     /// # }
     /// ```
-    ///
-    /// Due to a [soundness bug](https://github.com/time-rs/time/issues/293), the error value is
-    /// currently always returned on Unix-like platforms.
     #[cfg(feature = "local-offset")]
     #[cfg_attr(__time_03_docs, doc(cfg(feature = "local-offset")))]
     pub fn local_offset_at(datetime: OffsetDateTime) -> Result<Self, error::IndeterminateOffset> {
@@ -259,9 +256,7 @@ impl UtcOffset {
 #[cfg(feature = "formatting")]
 #[cfg_attr(__time_03_docs, doc(cfg(feature = "formatting")))]
 impl UtcOffset {
-    /// Format the `UtcOffset` using the provided format description. The formatted value will be
-    /// output to the provided writer. The format description will typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Format the `UtcOffset` using the provided [format description](crate::format_description).
     pub fn format_into(
         self,
         output: &mut impl io::Write,
@@ -270,9 +265,7 @@ impl UtcOffset {
         format.format_into(output, None, None, Some(self))
     }
 
-    /// Format the `UtcOffset` using the provided format description. The format description will
-    /// typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Format the `UtcOffset` using the provided [format description](crate::format_description).
     ///
     /// ```rust
     /// # use time::{format_description, macros::offset};
@@ -288,9 +281,8 @@ impl UtcOffset {
 #[cfg(feature = "parsing")]
 #[cfg_attr(__time_03_docs, doc(cfg(feature = "parsing")))]
 impl UtcOffset {
-    /// Parse a `UtcOffset` from the input using the provided format description. The format
-    /// description will typically be parsed by using
-    /// [`format_description::parse`](crate::format_description::parse()).
+    /// Parse a `UtcOffset` from the input using the provided [format
+    /// description](crate::format_description).
     ///
     /// ```rust
     /// # use time::{format_description, macros::offset, UtcOffset};