From 727834eb89654ed6fa9ba00fe4b65de3b1a28f87 Mon Sep 17 00:00:00 2001 From: KodrAus Date: Tue, 16 Nov 2021 11:16:58 +1000 Subject: [PATCH 1/3] some small doc cleanups --- shared/parser.rs | 2 +- src/builder.rs | 8 ++++---- src/fmt.rs | 24 ++++++++++-------------- src/lib.rs | 32 ++++++++++++++++++-------------- src/v1.rs | 5 ++--- 5 files changed, 35 insertions(+), 36 deletions(-) diff --git a/shared/parser.rs b/shared/parser.rs index 0ddf9dab..181bdac1 100644 --- a/shared/parser.rs +++ b/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| | | diff --git a/src/builder.rs b/src/builder.rs index e656eada..b1877779 100644 --- a/src/builder.rs +++ b/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(), /// ); /// ``` diff --git a/src/fmt.rs b/src/fmt.rs index 5bef01c7..99eb382d 100644 --- a/src/fmt.rs +++ b/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)] diff --git a/src/lib.rs b/src/lib.rs index c314387b..9bf97894 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -11,9 +11,8 @@ //! Generate and parse 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 +//! 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. //! //! They are particularly useful in distributed systems, though can be used in @@ -27,23 +26,27 @@ //! //! # 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. +//! +//! Other crate features can also be useful beyond the version support: +//! //! * `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`. +//! * `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 +103,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 +115,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 +216,7 @@ mod external; #[cfg(feature = "macros")] #[macro_use] mod macros; +#[doc(hidden)] #[cfg(feature = "macros")] pub extern crate uuid_macro; @@ -746,7 +750,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 diff --git a/src/v1.rs b/src/v1.rs index 0219adf7..86716baf 100644 --- a/src/v1.rs +++ b/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); /// From cf1940a56d40c92a218139d6f7c78a94d6b379aa Mon Sep 17 00:00:00 2001 From: KodrAus Date: Tue, 16 Nov 2021 11:26:01 +1000 Subject: [PATCH 2/3] introduce UUIDs and the API earlier in crate docs --- src/lib.rs | 36 ++++++++++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 9bf97894..bda094ea 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,11 +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). //! -//! 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 @@ -24,6 +30,28 @@ //! 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 can parse and format From 3b705af054e5baa7945269c0883d25f89bd2e33a Mon Sep 17 00:00:00 2001 From: Ashley Mannix Date: Tue, 16 Nov 2021 13:12:26 +1000 Subject: [PATCH 3/3] Update src/lib.rs Co-authored-by: Quinn <57224050+QnnOkabayashi@users.noreply.github.com> --- src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index bda094ea..bc7fc883 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -70,7 +70,7 @@ //! //! Other crate features can also be useful beyond the version support: //! -//! * `macros` - adds the `uuid!` macro that can parse UUIDs at compile time. +//! * `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