Merge pull request #565 from KodrAus/chore/doc-cleanups

some small doc cleanups

shared/parser.rs

@@ -79,7 +79,7 @@ const fn parse_hyphenated(s: &[u8]) -> Result<[u8; 16], ()> {
     // We look at two hex-encoded values (4 chars) at a time because
     // that's the size of the smallest group in a hyphenated UUID.
     // The indexes we're interested in are:
-    // 
+    //
     // uuid     : 936da01f-9abd-4d9d-80c7-02af85c822a8
     //            |   |   ||   ||   ||   ||   |   |
     // hyphens  : |   |   8|  13|  18|  23|   |   |

src/builder.rs

@@ -208,12 +208,12 @@ impl Uuid {
     ///
     /// ```
     /// # use uuid::Uuid;
-    /// let v = 0xd8d7d6d5d4d3d2d1c2c1b2b1a4a3a2a1u128;
+    /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
     ///
     /// let uuid = Uuid::from_u128_le(v);
     ///
     /// assert_eq!(
-    ///     "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
+    ///     "d8d7d6d5-d4d3-d2d1-c2c1-b2b1a4a3a2a1",
     ///     uuid.hyphenated().to_string(),
     /// );
     /// ```
@@ -690,12 +690,12 @@ impl Builder {
     ///
     /// ```
     /// # use uuid::Builder;
-    /// let v = 0xd8d7d6d5d4d3d2d1c2c1b2b1a4a3a2a1u128;
+    /// let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;
     ///
     /// let uuid = Builder::from_u128_le(v).into_uuid();
     ///
     /// assert_eq!(
-    ///     "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
+    ///     "d8d7d6d5-d4d3-d2d1-c2c1-b2b1a4a3a2a1",
     ///     uuid.hyphenated().to_string(),
     /// );
     /// ```

src/fmt.rs

@@ -9,10 +9,10 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Adapters for various formats for UUIDs
+//! Adapters for alternative string formats.
 
 use crate::{
-    std::{borrow::Borrow, fmt, str, ptr},
+    std::{borrow::Borrow, fmt, ptr, str},
     Uuid, Variant,
 };
 
@@ -61,36 +61,32 @@ impl fmt::UpperHex for Uuid {
     }
 }
 
-/// An adapter for formatting an [`Uuid`] as a hyphenated string.
-///
-/// Takes an owned instance of the [`Uuid`].
+/// Format a [`Uuid`] as a hyphenated string, like
+/// `67e55044-10b1-426f-9247-bb680e5fe0c8`.
 ///
 /// [`Uuid`]: ../struct.Uuid.html
 #[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
 #[repr(transparent)]
 pub struct Hyphenated(Uuid);
 
-/// An adapter for formatting an [`Uuid`] as a simple string.
-///
-/// Takes an owned instance of the [`Uuid`].
+/// Format a [`Uuid`] as a simple string, like
+/// `67e5504410b1426f9247bb680e5fe0c8`.
 ///
 /// [`Uuid`]: ../struct.Uuid.html
 #[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
 #[repr(transparent)]
 pub struct Simple(Uuid);
 
-/// An adapter for formatting an [`Uuid`] as a URN string.
-///
-/// Takes an owned instance of the [`Uuid`].
+/// Format a [`Uuid`] as a URN string, like
+/// `urn:uuid:67e55044-10b1-426f-9247-bb680e5fe0c8`.
 ///
 /// [`Uuid`]: ../struct.Uuid.html
 #[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
 #[repr(transparent)]
 pub struct Urn(Uuid);
 
-/// An adapter for formatting an [`Uuid`] as a braced hyphenated string.
-///
-/// Takes an owned instance of the [`Uuid`].
+/// Format a [`Uuid`] as a braced hyphenated string, like
+/// `{67e55044-10b1-426f-9247-bb680e5fe0c8}`.
 ///
 /// [`Uuid`]: ../struct.Uuid.html
 #[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]

src/lib.rs

@@ -9,12 +9,17 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Generate and parse UUIDs.
+//! Generate and parse universally unique identifiers (UUIDs).
 //!
-//! Provides support for Universally Unique Identifiers (UUIDs). A UUID is a
-//! unique 128-bit number, stored as 16 octets. UUIDs are used to  assign
-//! unique identifiers to entities without requiring a central allocating
-//! authority.
+//! Here's an example of a UUID:
+//!
+//! ```text
+//! 67e55044-10b1-426f-9247-bb680e5fe0c8
+//! ```
+//!
+//! A UUID is a unique 128-bit value, stored as 16 octets, and regularly formatted
+//! as a hex string in five groups. UUIDs are used to assign unique identifiers to
+//! entities without requiring a central allocating authority.
 //!
 //! They are particularly useful in distributed systems, though can be used in
 //! disparate areas, such as databases and network protocols.  Typically a UUID
@@ -25,25 +30,51 @@
 //! practical purposes, it can be assumed that an unintentional collision would
 //! be extremely unlikely.
 //!
+//! # Getting started
+//!
+//! Add the following to your `Cargo.toml`:
+//!
+//! ```toml
+//! [dependencies]
+//! uuid = { version = "0.8", features = ["v4"] }
+//! ```
+//!
+//! When you want a UUID, you can generate one:
+//!
+//! ```
+//! # fn main() {
+//! # #[cfg(feature = "v4")]
+//! # {
+//! use uuid::Uuid;
+//!
+//! let id = Uuid::new_v4();
+//! # }
+//! # }
+//! ```
+//!
 //! # Dependencies
 //!
-//! By default, this crate depends on nothing but `std` and cannot generate
-//! UUIDs. You need to enable the following Cargo features to enable
-//! various pieces of functionality:
+//! By default, this crate depends on nothing but `std` and can parse and format
+//! UUIDs, but cannot generate them. You need to enable the following Cargo
+//! features to enable various pieces of functionality:
 //!
 //! * `v1` - adds the [`Uuid::new_v1`] function and the ability to create a V1
-//!   using an implementation of [`v1::ClockSequence`] (usually
-//! [`v1::Context`]) and a timestamp from `time::timespec`.
+//!   UUID using an implementation of [`v1::ClockSequence`] (usually
+//! [`v1::Context`]) and a UNIX timestamp.
 //! * `v3` - adds the [`Uuid::new_v3`] function and the ability to create a V3
 //!   UUID based on the MD5 hash of some data.
 //! * `v4` - adds the [`Uuid::new_v4`] function and the ability to randomly
 //!   generate a UUID.
 //! * `v5` - adds the [`Uuid::new_v5`] function and the ability to create a V5
 //!   UUID based on the SHA1 hash of some data.
-//! * `macros` - adds the `uuid!` macro that can parse UUIDs at compile time.
-//! * `serde` - adds the ability to serialize and deserialize a UUID using the
-//!   `serde` crate.
-//! * `arbitrary` - adds an `Arbitrary` trait implementation to `Uuid`.
+//!
+//! Other crate features can also be useful beyond the version support:
+//!
+//! * `macros` - adds the `uuid!` macro that can parse UUIDs from string literals at compile time.
+//! * `serde` - adds the ability to serialize and deserialize a UUID using
+//!   `serde`.
+//! * `arbitrary` - adds an `Arbitrary` trait implementation to `Uuid` for
+//!   fuzzing.
 //! * `fast-rng` - when combined with `v4` uses a faster algorithm for
 //!   generating random UUIDs. This feature requires more dependencies to
 //!   compile, but is just as suitable for UUIDs as the default algorithm.
@@ -100,7 +131,7 @@
 //! ```
 //!
 //! You don't need the `js` feature to use `uuid` in WebAssembly if you're
-//! not enabling other features too.
+//! not also enabling `v4`.
 //!
 //! ## Embedded
 //!
@@ -112,7 +143,7 @@
 //! uuid = { version = "0.8", default-features = false }
 //! ```
 //!
-//! Some additional features are supported in no-std environments:
+//! Some additional features are supported in no-std environments though:
 //!
 //! * `v1`, `v3`, and `v5`
 //! * `serde`
@@ -213,6 +244,7 @@ mod external;
 #[cfg(feature = "macros")]
 #[macro_use]
 mod macros;
+#[doc(hidden)]
 #[cfg(feature = "macros")]
 pub extern crate uuid_macro;
 
@@ -746,7 +778,7 @@ impl AsRef<[u8]> for Uuid {
 
 #[cfg(feature = "serde")]
 pub mod serde {
-    //! Adapters for `serde`.
+    //! Adapters for alternative `serde` formats.
     //!
     //! This module contains adapters you can use with [`#[serde(with)]`](https://serde.rs/field-attrs.html#with)
     //! to change the way a [`Uuid`](../struct.Uuid.html) is serialized

src/v1.rs

@@ -166,7 +166,7 @@ impl Uuid {
     /// is seeded with a random value:
     ///
     /// ```rust
-    /// use uuid::v1::{Timestamp, Context};
+    /// # use uuid::v1::{Timestamp, Context};
     /// # use uuid::Uuid;
     /// # fn random_seed() -> u16 { 42 }
     /// let context = Context::new(random_seed());
@@ -183,9 +183,8 @@ impl Uuid {
     /// The timestamp can also be created manually as per RFC4122:
     ///
     /// ```
-    /// use uuid::v1::{Timestamp, Context};
+    /// # use uuid::v1::{Timestamp, Context};
     /// # use uuid::Uuid;
-    ///
     /// let context = Context::new(42);
     /// let ts = Timestamp::from_rfc4122(1497624119, 0);
     ///