From c0217078f5419792cb9a708bd17b70dbde076a75 Mon Sep 17 00:00:00 2001
From: Tobie Morgan Hitchcock <tobie@abcum.com>
Date: Sun, 28 Aug 2022 13:18:12 +0100
Subject: [PATCH] Improve documentation of Rust crate

---
 lib/src/kvs/ds.rs | 65 ++++++++++++++++++++++++++++++++++++++++++++++-
 lib/src/lib.rs    | 13 +++++-----
 2 files changed, 71 insertions(+), 7 deletions(-)

diff --git a/lib/src/kvs/ds.rs b/lib/src/kvs/ds.rs
index abdd85ca..138b15a3 100644
--- a/lib/src/kvs/ds.rs
+++ b/lib/src/kvs/ds.rs
@@ -133,6 +133,21 @@ impl Datastore {
 	}
 
 	/// Create a new transaction on this datastore
+	///
+	/// *You must ensure that a [`Transaction`] does not ever outlive a [`Datastore`] instance.*
+	///
+	/// ```rust,no_run
+	/// use surrealdb::Datastore;
+	/// use surrealdb::Error;
+	///
+	/// #[tokio::main]
+	/// async fn main() -> Result<(), Error> {
+	///     let ds = Datastore::new("file://database.db").await?;
+	///     let mut tx = ds.transaction(true, false).await?;
+	///     tx.cancel().await?;
+	///     Ok(())
+	/// }
+	/// ```
 	pub async fn transaction(&self, write: bool, lock: bool) -> Result<Transaction, Error> {
 		match &self.inner {
 			#[cfg(feature = "kv-echodb")]
@@ -179,6 +194,21 @@ impl Datastore {
 	}
 
 	/// Parse and execute an SQL query
+	///
+	/// ```rust,no_run
+	/// use surrealdb::Datastore;
+	/// use surrealdb::Error;
+	/// use surrealdb::Session;
+	///
+	/// #[tokio::main]
+	/// async fn main() -> Result<(), Error> {
+	///     let ds = Datastore::new("memory").await?;
+	///     let ses = Session::for_kv();
+	///     let ast = "USE NS test DB test; SELECT * FROM person;";
+	///     let res = ds.execute(ast, &ses, None, false).await?;
+	///     Ok(())
+	/// }
+	/// ```
 	pub async fn execute(
 		&self,
 		txt: &str,
@@ -212,6 +242,22 @@ impl Datastore {
 	}
 
 	/// Execute a pre-parsed SQL query
+	///
+	/// ```rust,no_run
+	/// use surrealdb::Datastore;
+	/// use surrealdb::Error;
+	/// use surrealdb::Session;
+	/// use surrealdb::sql::parse;
+	///
+	/// #[tokio::main]
+	/// async fn main() -> Result<(), Error> {
+	///     let ds = Datastore::new("memory").await?;
+	///     let ses = Session::for_kv();
+	///     let ast = parse("USE NS test DB test; SELECT * FROM person;")?;
+	///     let res = ds.process(ast, &ses, None, false).await?;
+	///     Ok(())
+	/// }
+	/// ```
 	pub async fn process(
 		&self,
 		ast: Query,
@@ -242,7 +288,24 @@ impl Datastore {
 		exe.execute(ctx, opt, ast).await
 	}
 
-	/// Execute a pre-parsed SQL query
+	/// Ensure a SQL [`Value`] is fully computed
+	///
+	/// ```rust,no_run
+	/// use surrealdb::Datastore;
+	/// use surrealdb::Error;
+	/// use surrealdb::Session;
+	/// use surrealdb::sql::Function;
+	/// use surrealdb::sql::Value;
+	///
+	/// #[tokio::main]
+	/// async fn main() -> Result<(), Error> {
+	///     let ds = Datastore::new("memory").await?;
+	///     let ses = Session::for_kv();
+	///     let val = Value::Function(Box::new(Function::Future(Value::True)));
+	///     let res = ds.compute(val, &ses, None, false).await?;
+	///     Ok(())
+	/// }
+	/// ```
 	pub async fn compute(
 		&self,
 		val: Value,
diff --git a/lib/src/lib.rs b/lib/src/lib.rs
index 2844883b..0dda24a8 100644
--- a/lib/src/lib.rs
+++ b/lib/src/lib.rs
@@ -1,10 +1,11 @@
-//! This library provides an easy-to-use client for [SurrealDB](https://surrealdb.com),
-//! the ultimate cloud database for tomorrow's applications. SurrealDB is a scalable,
-//! distributed, collaborative, document-graph database for the realtime web.
+//! This library provides the low-level database library implementation, and query language
+//! definition, for [SurrealDB](https://surrealdb.com), the ultimate cloud database for
+//! tomorrow's applications. SurrealDB is a scalable, distributed, collaborative, document-graph
+//! database for the realtime web.
 //!
-//! This library can be used to start an embedded in-memory datastore, an embedded
-//! datastore persisted to disk, or for connecting to a distributed [TiKV](https://tikv.org)
-//! key-value store.
+//! This library can be used to start an embedded in-memory datastore, an embedded datastore
+//! persisted to disk, a browser-based embedded datastore backed by IndexedDB, or for connecting
+//! to a distributed [TiKV](https://tikv.org) key-value store.
 
 #[macro_use]
 extern crate log;