more work on docs

src/lib.rs

@@ -381,7 +381,9 @@ impl Uuid {
     /// Callers should only trust the value returned by this method if they
     /// trust the UUID itself.
     ///
-    /// * [Variant Reference](http://tools.ietf.org/html/rfc4122#section-4.1.1)
+    /// # References
+    ///
+    /// * [Variant in RFC4122](http://tools.ietf.org/html/rfc4122#section-4.1.1)
     pub const fn get_variant(&self) -> Variant {
         match self.as_bytes()[8] {
             x if x & 0x80 == 0x00 => Variant::NCS,
@@ -399,6 +401,10 @@ impl Uuid {
     ///
     /// This represents the algorithm used to generate the contents.
     /// This method is the future-proof alternative to [`Uuid::get_version`].
+    ///
+    /// # References
+    ///
+    /// * [Version in RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.3)
     pub const fn get_version_num(&self) -> usize {
         (self.as_bytes()[6] >> 4) as usize
     }
@@ -410,6 +416,10 @@ impl Uuid {
     /// is returned. If you're trying to read the version for a future extension
     /// you can also use [`Uuid::get_version_num`] to unconditionally return a
     /// number.
+    ///
+    /// # References
+    ///
+    /// * [Version in RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.3)
     pub const fn get_version(&self) -> Option<Version> {
         match self.get_version_num() {
             0 if self.is_nil() => Some(Version::Nil),

src/parser.rs

@@ -32,6 +32,21 @@ impl Uuid {
     ///
     /// Any of the formats generated by this module (simple, hyphenated, urn)
     /// are supported by this parsing function.
+    ///
+    /// # Examples
+    ///
+    /// Parse a hyphenated UUID:
+    ///
+    /// ```
+    /// # use uuid::{Uuid, Version, Variant};
+    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
+    /// let uuid = Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000")?;
+    ///
+    /// assert_eq!(Some(Version::Random), uuid.get_version());
+    /// assert_eq!(Variant::RFC4122, uuid.get_variant());
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn parse_str(input: &str) -> Result<Uuid, Error> {
         Ok(Uuid::from_bytes(imp::parse_str(input)?))
     }

src/v1.rs

@@ -120,6 +120,10 @@ impl Timestamp {
 }
 
 /// A trait that abstracts over generation of UUID v1 "Clock Sequence" values.
+///
+/// # References
+///
+/// * [Clock Sequence in RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.5)
 pub trait ClockSequence {
     /// Return a 16-bit number that will be used as the "clock sequence" in
     /// the UUID. The number must be different if the time has changed since
@@ -165,6 +169,7 @@ impl Uuid {
     ///
     /// let context = Context::new(42);
     /// let ts = Timestamp::from_unix(&context, 1497624119, 1234);
+    ///
     /// let uuid = Uuid::new_v1(ts, &[1, 2, 3, 4, 5, 6]);
     ///
     /// assert_eq!(
@@ -181,6 +186,7 @@ impl Uuid {
     ///
     /// let context = Context::new(42);
     /// let ts = Timestamp::from_rfc4122(1497624119, 0);
+    ///
     /// let uuid = Uuid::new_v1(ts, &[1, 2, 3, 4, 5, 6]);
     ///
     /// assert_eq!(
@@ -190,7 +196,7 @@ impl Uuid {
     /// ```
     ///
     /// [`Timestamp`]: v1/struct.Timestamp.html
-    /// [`ClockSequence`]: v1/struct.ClockSequence.html
+    /// [`ClockSequence`]: v1/trait.ClockSequence.html
     /// [`Context`]: v1/struct.Context.html
     pub const fn new_v1(ts: Timestamp, node_id: &[u8; 6]) -> Self {
         let time_low = (ts.ticks & 0xFFFF_FFFF) as u32;