From ea771d0cb77254f3dd78e2c13230390b50cb2228 Mon Sep 17 00:00:00 2001
From: Feoramund <161657516+Feoramund@users.noreply.github.com>
Date: Sat, 22 Jun 2024 13:30:06 -0400
Subject: [PATCH] Update `uuid` package documentation

---
 core/encoding/uuid/doc.odin | 47 ++++++++++++++++++++++++++++++-------
 1 file changed, 39 insertions(+), 8 deletions(-)

diff --git a/core/encoding/uuid/doc.odin b/core/encoding/uuid/doc.odin
index a05698955..6fa375b72 100644
--- a/core/encoding/uuid/doc.odin
+++ b/core/encoding/uuid/doc.odin
@@ -1,15 +1,46 @@
 /*
 package uuid implements Universally Unique Identifiers according to the
-standard outlined in RFC 4122.
-
-See here for more information: https://www.rfc-editor.org/rfc/rfc4122.html
-
-Generation of versions 1 and 2 (the MAC address-based versions) are not yet
-implemented.
+standard originally outlined in RFC 4122 with additions from RFC 9562.
 
 The UUIDs are textually represented and read in the following string format:
-`00000000-0000-4000-8000-000000000000`
+`00000000-0000-v000-V000-000000000000`
 
-Outside of string representations, they are represented in memory by a 128-bit structure.
+`v` is where the version bits reside, and `V` is where the variant bits reside.
+The meaning of the other bits is version-dependent.
+
+Outside of string representations, UUIDs are represented in memory by a 128-bit
+structure organized as an array of 16 bytes.
+
+
+Of the UUID versions which may make use of random number generation, a
+requirement is placed upon them that the underlying generator be
+cryptographically-secure, per RFC 9562's suggestion.
+
+- Version 1 without a node argument.
+- Version 4 in all cases.
+- Version 6 without either a clock or node argument.
+- Version 7 in all cases.
+
+Here's an example of how to set up one:
+	
+	import "core:crypto"
+	import "core:encoding/uuid"
+
+	main :: proc() {
+		my_uuid: uuid.Identifier
+
+		{
+			// This scope will have a CSPRNG.
+			context.random_generator = crypto.random_generator()
+			my_uuid = uuid.generate_v7()
+		}
+
+		// Back to the default random number generator.
+	}
+
+
+For more information on the specifications, see here:
+- https://www.rfc-editor.org/rfc/rfc4122.html
+- https://www.rfc-editor.org/rfc/rfc9562.html
 */
 package uuid