Main documentation: simplify links and reflow text

src/lib.rs

@@ -1,32 +1,33 @@
 //! # Chrono: Date and Time for Rust
 //!
-//! Chrono aims to provide all functionality needed to do correct operations on dates and times in the
+//! Chrono aims to provide all functionality needed to do correct operations on dates and times in
-//! [proleptic Gregorian calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar):
+//! the [proleptic Gregorian calendar]:
 //!
-//! * The [`DateTime`](https://docs.rs/chrono/latest/chrono/struct.DateTime.html) type is timezone-aware
+//! * The [`DateTime`] type is timezone-aware by default, with separate timezone-naive types.
-//!   by default, with separate timezone-naive types.
 //! * Operations that may produce an invalid or ambiguous date and time return `Option` or
-//!   [`MappedLocalTime`](https://docs.rs/chrono/latest/chrono/offset/enum.MappedLocalTime.html).
+//!   [`MappedLocalTime`].
-//! * Configurable parsing and formatting with a `strftime` inspired date and time formatting syntax.
+//! * Configurable parsing and formatting with a `strftime` inspired date and time formatting
-//! * The [`Local`](https://docs.rs/chrono/latest/chrono/offset/struct.Local.html) timezone works with
+//!   syntax.
-//!   the current timezone of the OS.
+//! * The [`Local`] timezone works with the current timezone of the OS.
 //! * Types and operations are implemented to be reasonably efficient.
 //!
-//! Timezone data is not shipped with chrono by default to limit binary sizes. Use the companion crate
+//! Timezone data is not shipped with chrono by default to limit binary sizes. Use the companion
-//! [Chrono-TZ](https://crates.io/crates/chrono-tz) or [`tzfile`](https://crates.io/crates/tzfile) for
+//! crate [Chrono-TZ] or [`tzfile`] for full timezone support.
-//! full timezone support.
+//!
+//! [proleptic Gregorian calendar]: https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar
+//! [Chrono-TZ]: https://crates.io/crates/chrono-tz
+//! [`tzfile`]: https://crates.io/crates/tzfile
 //!
 //! ### Features
 //!
-//! Chrono supports various runtime environments and operating systems, and has
+//! Chrono supports various runtime environments and operating systems, and has several features
-//! several features that may be enabled or disabled.
+//! that may be enabled or disabled.
 //!
 //! Default features:
 //!
 //! - `alloc`: Enable features that depend on allocation (primarily string formatting).
-//! - `std`: Enables functionality that depends on the standard library. This
+//! - `std`: Enables functionality that depends on the standard library. This is a superset of
-//!   is a superset of `alloc` and adds interoperation with standard library types
+//!   `alloc` and adds interoperation with standard library types and traits.
-//!   and traits.
 //! - `clock`: Enables reading the local timezone (`Local`). This is a superset of `now`.
 //! - `now`: Enables reading the system time (`now`).
 //! - `wasmbind`: Interface with the JS Date API for the `wasm32` target.
@@ -35,16 +36,19 @@
 //!
 //! - `serde`: Enable serialization/deserialization via [serde].
 //! - `rkyv`: Deprecated, use the `rkyv-*` features.
-//! - `rkyv-16`: Enable serialization/deserialization via [rkyv], using 16-bit integers for integral `*size` types.
+//! - `rkyv-16`: Enable serialization/deserialization via [rkyv],
-//! - `rkyv-32`: Enable serialization/deserialization via [rkyv], using 32-bit integers for integral `*size` types.
+//!    using 16-bit integers for integral `*size` types.
-//! - `rkyv-64`: Enable serialization/deserialization via [rkyv], using 64-bit integers for integral `*size` types.
+//! - `rkyv-32`: Enable serialization/deserialization via [rkyv],
+//!    using 32-bit integers for integral `*size` types.
+//! - `rkyv-64`: Enable serialization/deserialization via [rkyv],
+//!    using 64-bit integers for integral `*size` types.
 //! - `rkyv-validation`: Enable rkyv validation support using `bytecheck`.
 //! - `rustc-serialize`: Enable serialization/deserialization via rustc-serialize (deprecated).
 //! - `arbitrary`: Construct arbitrary instances of a type with the Arbitrary crate.
-//! - `unstable-locales`: Enable localization. This adds various methods with a
+//! - `unstable-locales`: Enable localization. This adds various methods with a `_localized` suffix.
-//!   `_localized` suffix. The implementation and API may change or even be
+//!   The implementation and API may change or even be removed in a patch release. Feedback welcome.
-//!   removed in a patch release. Feedback welcome.
+//! - `oldtime`: This feature no longer has any effect; it used to offer compatibility with the
-//! - `oldtime`: This feature no longer has any effect; it used to offer compatibility with the `time` 0.1 crate.
+//!   `time` 0.1 crate.
 //!
 //! Note: The `rkyv{,-16,-32,-64}` features are mutually exclusive.
 //!
@@ -58,54 +62,45 @@
 //!
 //! ### Time delta / Duration
 //!
-//! Chrono has a [`TimeDelta`] type to represent the magnitude of a time span. This is an
+//! Chrono has a [`TimeDelta`] type to represent the magnitude of a time span. This is an "accurate"
-//! "accurate" duration represented as seconds and nanoseconds, and does not represent "nominal"
+//! duration represented as seconds and nanoseconds, and does not represent "nominal" components
-//! components such as days or months.
+//! such as days or months.
 //!
 //! The [`TimeDelta`] type was previously named `Duration` (and is still available as a type alias
 //! with that name). A notable difference with the similar [`core::time::Duration`] is that it is a
 //! signed value instead of unsigned.
 //!
-//! Chrono currently only supports a small number of operations with [`core::time::Duration`] .
+//! Chrono currently only supports a small number of operations with [`core::time::Duration`].
 //! You can convert between both types with the [`TimeDelta::from_std`] and [`TimeDelta::to_std`]
 //! methods.
 //!
 //! ### Date and Time
 //!
-//! Chrono provides a
+//! Chrono provides a [`DateTime`] type to represent a date and a time in a timezone.
-//! [**`DateTime`**](./struct.DateTime.html)
-//! type to represent a date and a time in a timezone.
 //!
-//! For more abstract moment-in-time tracking such as internal timekeeping
+//! For more abstract moment-in-time tracking such as internal timekeeping that is unconcerned with
-//! that is unconcerned with timezones, consider
+//! timezones, consider [`std::time::SystemTime`], which tracks your system clock, or
-//! [`time::SystemTime`](https://doc.rust-lang.org/std/time/struct.SystemTime.html),
+//! [`std::time::Instant`], which is an opaque but monotonically-increasing representation of a
-//! which tracks your system clock, or
+//! moment in time.
-//! [`time::Instant`](https://doc.rust-lang.org/std/time/struct.Instant.html), which
-//! is an opaque but monotonically-increasing representation of a moment in time.
 //!
-//! `DateTime` is timezone-aware and must be constructed from
+//! [`DateTime`] is timezone-aware and must be constructed from a [`TimeZone`] object, which defines
-//! the [**`TimeZone`**](./offset/trait.TimeZone.html) object,
+//! how the local date is converted to and back from the UTC date.
-//! which defines how the local date is converted to and back from the UTC date.
+//! There are three well-known [`TimeZone`] implementations:
-//! There are three well-known `TimeZone` implementations:
 //!
-//! * [**`Utc`**](./offset/struct.Utc.html) specifies the UTC time zone. It is most efficient.
+//! * [`Utc`] specifies the UTC time zone. It is most efficient.
 //!
-//! * [**`Local`**](./offset/struct.Local.html) specifies the system local time zone.
+//! * [`Local`] specifies the system local time zone.
 //!
-//! * [**`FixedOffset`**](./offset/struct.FixedOffset.html) specifies
+//! * [`FixedOffset`] specifies an arbitrary, fixed time zone such as UTC+09:00 or UTC-10:30.
-//!   an arbitrary, fixed time zone such as UTC+09:00 or UTC-10:30.
+//!   This often results from the parsed textual date and time. Since it stores the most information
-//!   This often results from the parsed textual date and time.
+//!   and does not depend on the system environment, you would want to normalize other `TimeZone`s
-//!   Since it stores the most information and does not depend on the system environment,
+//!   into this type.
-//!   you would want to normalize other `TimeZone`s into this type.
 //!
-//! `DateTime`s with different `TimeZone` types are distinct and do not mix,
+//! [`DateTime`]s with different [`TimeZone`] types are distinct and do not mix, but can be
-//! but can be converted to each other using
+//! converted to each other using the [`DateTime::with_timezone`] method.
-//! the [`DateTime::with_timezone`](./struct.DateTime.html#method.with_timezone) method.
 //!
-//! You can get the current date and time in the UTC time zone
+//! You can get the current date and time in the UTC time zone ([`Utc::now()`]) or in the local time
-//! ([`Utc::now()`](./offset/struct.Utc.html#method.now))
+//! zone ([`Local::now()`]).
-//! or in the local time zone
-//! ([`Local::now()`](./offset/struct.Local.html#method.now)).
 //!
 //! ```
 //! # #[cfg(feature = "now")] {
@@ -125,9 +120,9 @@
 //! # }
 //! ```
 //!
-//! Alternatively, you can create your own date and time.
+//! Alternatively, you can create your own date and time. This is a bit verbose due to Rust's lack
-//! This is a bit verbose due to Rust's lack of function and method overloading,
+//! of function and method overloading, but in turn we get a rich combination of initialization
-//! but in turn we get a rich combination of initialization methods.
+//! methods.
 //!
 //! ```
 //! use chrono::offset::MappedLocalTime;
@@ -202,9 +197,8 @@
 //! # doctest().unwrap();
 //! ```
 //!
-//! Various properties are available to the date and time, and can be altered individually.
+//! Various properties are available to the date and time, and can be altered individually. Most of
-//! Most of them are defined in the traits [`Datelike`](./trait.Datelike.html) and
+//! them are defined in the traits [`Datelike`] and [`Timelike`] which you should `use` before.
-//! [`Timelike`](./trait.Timelike.html) which you should `use` before.
 //! Addition and subtraction is also supported.
 //! The following illustrates most supported operations to the date and time:
 //!
@@ -268,20 +262,18 @@
 //!
 //! ### Formatting and Parsing
 //!
-//! Formatting is done via the [`format`](./struct.DateTime.html#method.format) method,
+//! Formatting is done via the [`format`](DateTime::format()) method, which format is equivalent to
-//! which format is equivalent to the familiar `strftime` format.
+//! the familiar `strftime` format.
 //!
-//! See [`format::strftime`](./format/strftime/index.html#specifiers)
+//! See [`format::strftime`](format::strftime#specifiers) documentation for full syntax and list of
-//! documentation for full syntax and list of specifiers.
+//! specifiers.
 //!
 //! The default `to_string` method and `{:?}` specifier also give a reasonable representation.
-//! Chrono also provides [`to_rfc2822`](./struct.DateTime.html#method.to_rfc2822) and
+//! Chrono also provides [`to_rfc2822`](DateTime::to_rfc2822) and
-//! [`to_rfc3339`](./struct.DateTime.html#method.to_rfc3339) methods
+//! [`to_rfc3339`](DateTime::to_rfc3339) methods for well-known formats.
-//! for well-known formats.
 //!
-//! Chrono now also provides date formatting in almost any language without the
+//! Chrono now also provides date formatting in almost any language without the help of an
-//! help of an additional C library. This functionality is under the feature
+//! additional C library. This functionality is under the feature `unstable-locales`:
-//! `unstable-locales`:
 //!
 //! ```toml
 //! chrono = { version = "0.4", features = ["unstable-locales"] }
@@ -326,24 +318,18 @@
 //!
 //! Parsing can be done with two methods:
 //!
-//! 1. The standard [`FromStr`](https://doc.rust-lang.org/std/str/trait.FromStr.html) trait
+//! 1. The standard [`FromStr`](std::str::FromStr) trait (and [`parse`](str::parse) method on a
-//!    (and [`parse`](https://doc.rust-lang.org/std/primitive.str.html#method.parse) method
+//!    string) can be used for parsing `DateTime<FixedOffset>`, `DateTime<Utc>` and
-//!    on a string) can be used for parsing `DateTime<FixedOffset>`, `DateTime<Utc>` and
+//!    `DateTime<Local>` values. This parses what the `{:?}` ([`std::fmt::Debug`] format specifier
-//!    `DateTime<Local>` values. This parses what the `{:?}`
+//!    prints, and requires the offset to be present.
-//!    ([`std::fmt::Debug`](https://doc.rust-lang.org/std/fmt/trait.Debug.html))
-//!    format specifier prints, and requires the offset to be present.
 //!
-//! 2. [`DateTime::parse_from_str`](./struct.DateTime.html#method.parse_from_str) parses
+//! 2. [`DateTime::parse_from_str`] parses a date and time with offsets and returns
-//!    a date and time with offsets and returns `DateTime<FixedOffset>`.
+//!    `DateTime<FixedOffset>`. This should be used when the offset is a part of input and the
-//!    This should be used when the offset is a part of input and the caller cannot guess that.
+//!    caller cannot guess that. It *cannot* be used when the offset can be missing.
-//!    It *cannot* be used when the offset can be missing.
+//!    [`DateTime::parse_from_rfc2822`] and [`DateTime::parse_from_rfc3339`] are similar but for
-//!    [`DateTime::parse_from_rfc2822`](./struct.DateTime.html#method.parse_from_rfc2822)
+//!    well-known formats.
-//!    and
-//!    [`DateTime::parse_from_rfc3339`](./struct.DateTime.html#method.parse_from_rfc3339)
-//!    are similar but for well-known formats.
 //!
-//! More detailed control over the parsing process is available via
+//! More detailed control over the parsing process is available via [`format`](mod@format) module.
-//! [`format`](./format/index.html) module.
 //!
 //! ```rust
 //! use chrono::prelude::*;
@@ -375,8 +361,8 @@
 //! assert!(DateTime::parse_from_str("Sat Nov 28 12:00:09 2014", "%a %b %e %T %Y").is_err());
 //! ```
 //!
-//! Again : See [`format::strftime`](./format/strftime/index.html#specifiers)
+//! Again: See [`format::strftime`](format::strftime#specifiers) documentation for full syntax and
-//! documentation for full syntax and list of specifiers.
+//! list of specifiers.
 //!
 //! ### Conversion from and to EPOCH timestamps
 //!
@@ -406,20 +392,16 @@
 //!
 //! ### Naive date and time
 //!
-//! Chrono provides naive counterparts to `Date`, (non-existent) `Time` and `DateTime`
+//! Chrono provides naive counterparts to `Date`, (non-existent) `Time` and `DateTime` as
-//! as [**`NaiveDate`**](./naive/struct.NaiveDate.html),
+//! [`NaiveDate`], [`NaiveTime`] and [`NaiveDateTime`] respectively.
-//! [**`NaiveTime`**](./naive/struct.NaiveTime.html) and
-//! [**`NaiveDateTime`**](./naive/struct.NaiveDateTime.html) respectively.
 //!
-//! They have almost equivalent interfaces as their timezone-aware twins,
+//! They have almost equivalent interfaces as their timezone-aware twins, but are not associated to
-//! but are not associated to time zones obviously and can be quite low-level.
+//! time zones obviously and can be quite low-level. They are mostly useful for building blocks for
-//! They are mostly useful for building blocks for higher-level types.
+//! higher-level types.
 //!
 //! Timezone-aware `DateTime` and `Date` types have two methods returning naive versions:
-//! [`naive_local`](./struct.DateTime.html#method.naive_local) returns
+//! [`naive_local`](DateTime::naive_local) returns a view to the naive local time,
-//! a view to the naive local time,
+//! and [`naive_utc`](DateTime::naive_utc) returns a view to the naive UTC time.
-//! and [`naive_utc`](./struct.DateTime.html#method.naive_utc) returns
-//! a view to the naive UTC time.
 //!
 //! ## Limitations
 //!
@@ -427,7 +409,7 @@
 //! * Date types are limited to about +/- 262,000 years from the common epoch.
 //! * Time types are limited to nanosecond accuracy.
 //! * Leap seconds can be represented, but Chrono does not fully support them.
-//!   See [Leap Second Handling](https://docs.rs/chrono/latest/chrono/naive/struct.NaiveTime.html#leap-second-handling).
+//!   See [Leap Second Handling](NaiveTime#leap-second-handling).
 //!
 //! ## Rust version requirements
 //!