Update documentation (#52)

README.md

@@ -84,7 +84,7 @@ assert my_uuid < uuid7()
 - `subsec_a`: 12 bits allocated to sub-second precision values
 - `var`: 2 bit UUID variant (10)
 - `subsec_b`: 8 bits allocated to sub-second precision values
-- `rand`: The remaining 54 bits are filled with pseudo-random data
+- `rand`: The remaining 54 bits are filled with [cryptographically strong random data][python randbits]
 
  20 extra bits dedicated to sub-second precision provide nanosecond resolution. The `unix_ts` and `subsec` fields guarantee the order of UUIDs generated within the same nanosecond by monotonically incrementing the timer.
 
@@ -125,4 +125,5 @@ Mean +- std dev: 4.94 us +- 0.24 us
 [draft repository]: https://github.com/uuid6/uuid6-ietf-draft
 [draft 04]: https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04#section-5.2
 [cloud shell]: https://cloud.google.com/shell/docs
+[python randbits]: https://docs.python.org/3/library/secrets.html#secrets.randbits
 [bench]: https://github.com/oittaa/uuid6-python/blob/main/bench.sh

src/uuid6/__init__.py

@@ -79,7 +79,11 @@ def _subsec_encode(value: int) -> int:
 
 
 def uuid6(clock_seq: int = None) -> UUID:
-    r"""Generate a UUID from sequence number, and the current time.
+    r"""UUID version 6 is a field-compatible version of UUIDv1, reordered for
+    improved DB locality.  It is expected that UUIDv6 will primarily be
+    used in contexts where there are existing v1 UUIDs.  Systems that do
+    not involve legacy UUIDv1 SHOULD consider using UUIDv7 instead.
+
     If 'clock_seq' is given, it is used as the sequence number;
     otherwise a random 14-bit sequence number is chosen."""
 
@@ -105,13 +109,14 @@ def uuid6(clock_seq: int = None) -> UUID:
 
 
 def uuid7() -> UUID:
-    r"""The UUIDv7 format is designed to encode a Unix timestamp with
-    arbitrary sub-second precision.  The key property provided by UUIDv7
-    is that timestamp values generated by one system and parsed by
-    another are guaranteed to have sub-second precision of either the
-    generator or the parser, whichever is less.  Additionally, the system
-    parsing the UUIDv7 value does not need to know which precision was
-    used during encoding in order to function correctly."""
+    r"""UUID version 7 features a time-ordered value field derived from the
+    widely implemented and well known Unix Epoch timestamp source, the
+    number of milliseconds seconds since midnight 1 Jan 1970 UTC, leap
+    seconds excluded.  As well as improved entropy characteristics over
+    versions 1 or 6.
+
+    Implementations SHOULD utilize UUID version 7 over UUID version 1 and
+    6 if possible."""
 
     global _last_v7_timestamp