From e725b3e8e625f3e6870a082ba143bbb6751005d2 Mon Sep 17 00:00:00 2001
From: Tobie Morgan Hitchcock <tobie@surrealdb.com>
Date: Sat, 6 May 2023 00:53:26 +0100
Subject: [PATCH] Add detailed code comments for `Value` enum variants (#1938)

---
 lib/src/sql/value/value.rs | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/lib/src/sql/value/value.rs b/lib/src/sql/value/value.rs
index bfda77d0..16382de3 100644
--- a/lib/src/sql/value/value.rs
+++ b/lib/src/sql/value/value.rs
@@ -107,6 +107,13 @@ pub fn whats(i: &str) -> IResult<&str, Values> {
 #[serde(rename = "$surrealdb::private::sql::Value")]
 #[format(Named)]
 pub enum Value {
+	// These value types are simple values which
+	// can be used in query responses sent to
+	// the client. They typically do not need to
+	// be computed, unless an un-computed value
+	// is present inside an Array or Object type.
+	// These types can also be used within indexes
+	// and sort according to their order below.
 	#[default]
 	None,
 	Null,
@@ -120,11 +127,17 @@ pub enum Value {
 	Object(Object),
 	Geometry(Geometry),
 	Bytes(Bytes),
-	// ---
+	Thing(Thing),
+	// These Value types are un-computed values
+	// and are not used in query responses sent
+	// to the client. These types need to be
+	// computed, in order to convert them into
+	// one of the simple types listed above.
+	// These types are first computed into a
+	// simple type before being used in indexes.
 	Param(Param),
 	Idiom(Idiom),
 	Table(Table),
-	Thing(Thing),
 	Model(Model),
 	Regex(Regex),
 	Block(Box<Block>),