From d7a57351379e2b5b5a92346d952ea9892c2b683f Mon Sep 17 00:00:00 2001
From: AdamMagued <adammagued@users.noreply.github.com>
Date: Fri, 2 Oct 2026 21:48:38 +0000
Subject: [PATCH] docs: clarify Invalid Variant documentation and usage

Any valid 128-bit UUID classifies into RFC4122, Reserved, Microsoft, or
Future. Variant never returns Invalid on a 16-byte UUID; Invalid represents
an uninitialized or non-UUID sentinel.

Update documentation for Variant, the variant constants, and (UUID).Variant
to make this explicit. Additionally, document the invalid cases in unit test
tables where parsing returns an error, and add an explicit test verifying
Variant.String() returns "Invalid" for Variant(0) / Invalid.

Fixes #91
---
 uuid.go      | 12 +++++++++++-
 uuid_test.go | 27 +++++++++++++++++++++++++++
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/uuid.go b/uuid.go
index dc75cee..685db49 100644
--- a/uuid.go
+++ b/uuid.go
@@ -23,9 +23,15 @@ type UUID [16]byte
 type Version byte
 
 // A Variant represents a UUID's variant.
+//
+// Any valid 128-bit UUID classifies into RFC4122, Reserved, Microsoft, or
+// Future. Invalid represents an uninitialized or non-UUID sentinel.
 type Variant byte
 
-// Constants returned by Variant.
+// Constants representing UUID variants.
+//
+// Any valid 128-bit UUID classifies into RFC4122, Reserved, Microsoft, or
+// Future. Invalid represents an uninitialized or non-UUID sentinel.
 const (
 	Invalid   = Variant(iota) // Invalid UUID
 	RFC4122                   // The variant specified in RFC9562(obsoletes RFC4122).
@@ -297,6 +303,10 @@ func encodeHex(dst []byte, uuid UUID) {
 }
 
 // Variant returns the variant encoded in uuid.
+//
+// Any valid 128-bit UUID classifies into RFC4122, Reserved, Microsoft, or
+// Future. Variant never returns Invalid, which represents an uninitialized or
+// non-UUID sentinel.
 func (uuid UUID) Variant() Variant {
 	switch {
 	case (uuid[8] & 0xc0) == 0x80:
diff --git a/uuid_test.go b/uuid_test.go
index 906ecbe..4340f82 100644
--- a/uuid_test.go
+++ b/uuid_test.go
@@ -60,6 +60,8 @@ var tests = []test{
 	{"f47ac10b-58cc-4372-e567-0e02b2c3d479", 4, Future, true},
 	{"f47ac10b-58cc-4372-f567-0e02b2c3d479", 4, Future, true},
 
+	// For invalid UUID strings, Parse returns an error and the test runner returns
+	// early without evaluating version or variant. Invalid is used as a placeholder.
 	{"f47ac10b158cc-5372-a567-0e02b2c3d479", 0, Invalid, false},
 	{"f47ac10b-58cc25372-a567-0e02b2c3d479", 0, Invalid, false},
 	{"f47ac10b-58cc-53723a567-0e02b2c3d479", 0, Invalid, false},
@@ -165,6 +167,31 @@ func TestConstants(t *testing.T) {
 	}
 }
 
+func TestVariantInvalid(t *testing.T) {
+	if s := Invalid.String(); s != "Invalid" {
+		t.Errorf("Invalid.String() = %q, want %q", s, "Invalid")
+	}
+	if s := Variant(0).String(); s != "Invalid" {
+		t.Errorf("Variant(0).String() = %q, want %q", s, "Invalid")
+	}
+}
+
+func TestVariantAllBytes(t *testing.T) {
+	for b := 0; b <= 0xff; b++ {
+		var u UUID
+		u[8] = byte(b)
+		v := u.Variant()
+		if v == Invalid {
+			t.Errorf("UUID with byte[8]=%#x returned Invalid variant", b)
+		}
+		switch v {
+		case RFC4122, Reserved, Microsoft, Future:
+		default:
+			t.Errorf("UUID with byte[8]=%#x returned unexpected variant %v", b, v)
+		}
+	}
+}
+
 func TestRandomUUID(t *testing.T) {
 	m := make(map[string]bool)
 	for x := 1; x < 32; x++ {