[Documentation] Improve Rust client code samples a bit (#3699)

core/src/options.rs

@@ -1,6 +1,7 @@
 use std::time::Duration;
 
 /// Configuration for the engine behaviour
+///
 /// The defaults are optimal so please only modify these if you know deliberately why you are modifying them.
 #[derive(Clone, Copy, Debug)]
 #[doc(hidden)]

lib/README.md

@@ -39,30 +39,38 @@ This library enables simple and advanced querying of an embedded or remote datab
 ```rust
 use serde::{Deserialize, Serialize};
 use serde_json::json;
-use std::borrow::Cow;
 use surrealdb::sql;
 use surrealdb::sql::Thing;
 use surrealdb::Surreal;
 use surrealdb::engine::remote::ws::Ws;
 use surrealdb::opt::auth::Root;
+use surrealdb::Error;
 
 #[derive(Serialize, Deserialize)]
 struct Name {
-    first: Cow<'static, str>,
-    last: Cow<'static, str>,
+    first: String,
+    last: String,
 }
 
 #[derive(Serialize, Deserialize)]
 struct Person {
     #[serde(skip_serializing)]
     id: Option<Thing>,
-    title: Cow<'static, str>,
+    title: String,
     name: Name,
     marketing: bool,
 }
 
+// Install at https://surrealdb.com/install 
+// and use `surreal start --user root --pass root`
+// to start a working database to take the following queries
+// 
+// See the results via `surreal sql --ns namespace --db database --pretty` 
+// or https://surrealist.app/
+// followed by the query `SELECT * FROM person;`
+
 #[tokio::main]
-async fn main() -> surrealdb::Result<()> {
+async fn main() -> Result<(), Error> {
     let db = Surreal::new::<Ws>("localhost:8000").await?;
 
     // Signin as a namespace, database, or root user
@@ -113,7 +121,7 @@ async fn main() -> surrealdb::Result<()> {
     let people: Vec<Person> = db.select("person").await?;
 
     // Perform a custom advanced query
-    let sql = r#"
+    let query = r#"
         SELECT marketing, count()
         FROM type::table($table)
         GROUP BY marketing
@@ -123,7 +131,7 @@ async fn main() -> surrealdb::Result<()> {
         .bind(("table", "person"))
         .await?;
 
-    // Delete all people upto but not including Jaime
+    // Delete all people up to but not including Jaime
     let people: Vec<Person> = db.delete("person").range(.."jaime").await?;
 
     // Delete all people

lib/src/api/method/mod.rs

@@ -140,9 +140,10 @@ where
 	/// Initialises a new unconnected instance of the client
 	///
 	/// This makes it easy to create a static singleton of the client. The static singleton
-	/// ensures that a single database instance is available across very large or complicated
-	/// applications. With the singleton, only one connection to the database is instantiated,
-	/// and the database connection does not have to be shared across components or controllers.
+	/// pattern in the example below ensures that a single database instance is available
+	/// across very large or complicated applications. With the singleton, only one connection
+	/// to the database is instantiated, and the database connection does not have to be shared
+	/// across components or controllers.
 	///
 	/// # Examples
 	///
@@ -151,7 +152,6 @@ where
 	/// ```no_run
 	/// use once_cell::sync::Lazy;
 	/// use serde::{Serialize, Deserialize};
-	/// use std::borrow::Cow;
 	/// use surrealdb::Surreal;
 	/// use surrealdb::opt::auth::Root;
 	/// use surrealdb::engine::remote::ws::Ws;
@@ -162,7 +162,7 @@ where
 	///
 	/// #[derive(Serialize, Deserialize)]
 	/// struct Person {
-	///     name: Cow<'static, str>,
+	///     name: String,
 	/// }
 	///
 	/// #[tokio::main]
@@ -194,7 +194,6 @@ where
 	/// ```no_run
 	/// use once_cell::sync::Lazy;
 	/// use serde::{Serialize, Deserialize};
-	/// use std::borrow::Cow;
 	/// use surrealdb::Surreal;
 	/// use surrealdb::engine::any::Any;
 	/// use surrealdb::opt::auth::Root;
@@ -204,7 +203,7 @@ where
 	///
 	/// #[derive(Serialize, Deserialize)]
 	/// struct Person {
-	///     name: Cow<'static, str>,
+	///     name: String,
 	/// }
 	///
 	/// #[tokio::main]
@@ -323,9 +322,9 @@ where
 	/// use serde::Serialize;
 	///
 	/// #[derive(Serialize)]
-	/// struct Name<'a> {
-	///     first: &'a str,
-	///     last: &'a str,
+	/// struct Name {
+	///     first: String,
+	///     last: String,
 	/// }
 	///
 	/// # #[tokio::main]
@@ -334,8 +333,8 @@ where
 	/// #
 	/// // Assign the variable on the connection
 	/// db.set("name", Name {
-	///     first: "Tobie",
-	///     last: "Morgan Hitchcock",
+	///     first: "Tobie".into(),
+	///     last: "Morgan Hitchcock".into(),
 	/// }).await?;
 	///
 	/// // Use the variable in a subsequent query
@@ -363,9 +362,9 @@ where
 	/// use serde::Serialize;
 	///
 	/// #[derive(Serialize)]
-	/// struct Name<'a> {
-	///     first: &'a str,
-	///     last: &'a str,
+	/// struct Name {
+	///     first: String,
+	///     last: String,
 	/// }
 	///
 	/// # #[tokio::main]
@@ -374,8 +373,8 @@ where
 	/// #
 	/// // Assign the variable on the connection
 	/// db.set("name", Name {
-	///     first: "Tobie",
-	///     last: "Morgan Hitchcock",
+	///     first: "Tobie".into(),
+	///     last: "Morgan Hitchcock".into(),
 	/// }).await?;
 	///
 	/// // Use the variable in a subsequent query
@@ -405,9 +404,9 @@ where
 	/// use surrealdb::opt::auth::Scope;
 	///
 	/// #[derive(Debug, Serialize)]
-	/// struct AuthParams<'a> {
-	///     email: &'a str,
-	///     password: &'a str,
+	/// struct AuthParams {
+	///     email: String,
+	///     password: String,
 	/// }
 	///
 	/// # #[tokio::main]
@@ -438,8 +437,8 @@ where
 	///     database: "database",
 	///     scope: "user_scope",
 	///     params: AuthParams {
-	///         email: "john.doe@example.com",
-	///         password: "password123",
+	///         email: "john.doe@example.com".into(),
+	///         password: "password123".into(),
 	///     },
 	/// }).await?;
 	/// #
@@ -539,9 +538,9 @@ where
 	/// use surrealdb::opt::auth::Scope;
 	///
 	/// #[derive(Debug, Serialize)]
-	/// struct AuthParams<'a> {
-	///     email: &'a str,
-	///     password: &'a str,
+	/// struct AuthParams {
+	///     email: String,
+	///     password: String,
 	/// }
 	///
 	/// # #[tokio::main]
@@ -557,8 +556,8 @@ where
 	///     database: "database",
 	///     scope: "user_scope",
 	///     params: AuthParams {
-	///         email: "john.doe@example.com",
-	///         password: "password123",
+	///         email: "john.doe@example.com".into(),
+	///         password: "password123".into(),
 	///     },
 	/// }).await?;
 	/// #
@@ -737,8 +736,8 @@ where
 	/// }
 	///
 	/// #[derive(Serialize)]
-	/// struct User<'a> {
-	///     name: &'a str,
+	/// struct User {
+	///     name: &'static str,
 	///     settings: Settings,
 	/// }
 	///
@@ -894,8 +893,8 @@ where
 	/// }
 	///
 	/// #[derive(Serialize)]
-	/// struct User<'a> {
-	///     name: &'a str,
+	/// struct User {
+	///     name: &'static str,
 	///     settings: Settings,
 	/// }
 	///

lib/src/lib.rs

@@ -14,29 +14,39 @@
 //! # Examples
 //!
 //! ```no_run
+//! use std::borrow::Cow;
 //! use serde::{Serialize, Deserialize};
 //! use serde_json::json;
-//! use std::borrow::Cow;
-//! use surrealdb::{Result, Surreal};
-//! use surrealdb::sql;
+//! use surrealdb::{Error, Surreal};
 //! use surrealdb::opt::auth::Root;
 //! use surrealdb::engine::remote::ws::Ws;
 //!
 //! #[derive(Serialize, Deserialize)]
+//! struct Person {
+//!     title: String,
+//!     name: Name,
+//!     marketing: bool,
+//! }
+//!
+//! // Pro tip: Replace String with Cow<'static, str> to
+//! // avoid unnecessary heap allocations when inserting
+//!
+//! #[derive(Serialize, Deserialize)]
 //! struct Name {
 //!     first: Cow<'static, str>,
 //!     last: Cow<'static, str>,
 //! }
 //!
-//! #[derive(Serialize, Deserialize)]
-//! struct Person {
-//!     title: Cow<'static, str>,
-//!     name: Name,
-//!     marketing: bool,
-//! }
-//!
+//! // Install at https://surrealdb.com/install
+//! // and use `surreal start --user root --pass root`
+//! // to start a working database to take the following queries
+
+//! // See the results via `surreal sql --ns namespace --db database --pretty`
+//! // or https://surrealist.app/
+//! // followed by the query `SELECT * FROM person;`
+
 //! #[tokio::main]
-//! async fn main() -> Result<()> {
+//! async fn main() -> Result<(), Error> {
 //!     let db = Surreal::new::<Ws>("localhost:8000").await?;
 //!
 //!     // Signin as a namespace, database, or root user
@@ -81,13 +91,13 @@
 //!     let people: Vec<Person> = db.select("person").await?;
 //!
 //!     // Perform a custom advanced query
-//!     let sql = r#"
+//!     let query = r#"
 //!         SELECT marketing, count()
 //!         FROM type::table($table)
 //!         GROUP BY marketing
 //!     "#;
 //!
-//!     let groups = db.query(sql)
+//!     let groups = db.query(query)
 //!         .bind(("table", "person"))
 //!         .await?;
 //!