Update docs

Author: blackbeam

src/conn/mod.rs

@@ -146,6 +146,7 @@ impl ConnInner {
     }
 }
 
+/// MySql server connection.
 #[derive(Debug)]
 pub struct Conn {
     inner: Box<ConnInner>,

src/lib.rs

@@ -40,7 +40,6 @@
 //!         Payment { customer_id: 7, amount: 8, account_name: None },
 //!         Payment { customer_id: 9, amount: 10, account_name: Some("bar".into()) },
 //!     ];
-//!     let payments_clone = payments.clone();
 //!
 //!     let database_url = /* ... */
 //!     # get_opts();
@@ -58,17 +57,17 @@
 //!     ).await?;
 //!
 //!     // Save payments
-//!     let params = payments_clone.into_iter().map(|payment| {
+//!     let params = payments.clone().into_iter().map(|payment| {
 //!         params! {
 //!             "customer_id" => payment.customer_id,
 //!             "amount" => payment.amount,
-//!             "account_name" => payment.account_name.clone(),
+//!             "account_name" => payment.account_name,
 //!         }
 //!     });
 //!
 //!     conn.exec_batch(
 //!         r"INSERT INTO payment (customer_id, amount, account_name)
-//!             VALUES (:customer_id, :amount, :account_name)",
+//!           VALUES (:customer_id, :amount, :account_name)",
 //!         params,
 //!     ).await?;
 //!

src/queryable/mod.rs

@@ -101,6 +101,7 @@ impl Conn {
     }
 }
 
+/// Methods of this trait used to execute database queries.
 pub trait Queryable: Send {
     /// Executes `COM_PING`.
     fn ping(&mut self) -> BoxFuture<'_, ()>;
@@ -114,14 +115,23 @@ pub trait Queryable: Send {
         Q: AsRef<str> + Send + Sync + 'a;
 
     /// Prepares the given statement.
+    ///
+    /// Note, that `Statement` will exist only in the context of this queryable.
+    ///
+    /// Also note, that this call may close the least recently used statement
+    /// if statement cache is at its capacity (see. [`stmt_cache_size`]).
     fn prep<'a, Q>(&'a mut self, query: Q) -> BoxFuture<'a, Statement>
     where
         Q: AsRef<str> + Sync + Send + 'a;
 
     /// Closes the given statement.
+    ///
+    /// Usually there is no need to explicitly close statements (see. [`stmt_cache_size`]).
     fn close(&mut self, stmt: Statement) -> BoxFuture<'_, ()>;
 
     /// Executes the given statement with the given params.
+    ///
+    /// It'll prepare `stmt`, if necessary.
     fn exec_iter<'a: 's, 's, Q, P>(
         &'a mut self,
         stmt: &'s Q,
@@ -137,13 +147,13 @@ pub trait Queryable: Send {
         Q: AsRef<str> + Send + Sync + 'a,
         T: FromRow + Send + 'static;
 
-    /// Performs the given query and returns the firt row of the first result set.
+    /// Performs the given query and returns the first row of the first result set.
     fn query_first<'a, T, Q>(&'a mut self, query: Q) -> BoxFuture<'a, Option<T>>
     where
         Q: AsRef<str> + Send + Sync + 'a,
         T: FromRow + Send + 'static;
 
-    /// Performs the given query and returns the firt row of the first result set.
+    /// Performs the given query and returns the first row of the first result set.
     fn query_map<'a, T, F, Q, U>(&'a mut self, query: Q, f: F) -> BoxFuture<'a, Vec<U>>
     where
         Q: AsRef<str> + Send + Sync + 'a,
@@ -164,7 +174,9 @@ pub trait Queryable: Send {
     where
         Q: AsRef<str> + Send + Sync + 'a;
 
-    /// Prepares the given statement, and exectues it with each item in the given params iterator.
+    /// Exectues the given statement with each item in the given params iterator.
+    ///
+    /// It'll prepare `stmt`, if necessary.
     fn exec_batch<'a: 'b, 'b, S, P, I>(
         &'a mut self,
         stmt: &'b S,
@@ -177,13 +189,17 @@ pub trait Queryable: Send {
         P: Into<Params> + Send;
 
     /// Exectues the given statement and collects the first result set.
+    ///
+    /// It'll prepare `stmt`, if necessary.
     fn exec<'a: 'b, 'b, T, S, P>(&'a mut self, stmt: &'b S, params: P) -> BoxFuture<'b, Vec<T>>
     where
         S: StatementLike + ?Sized + 'b,
         P: Into<Params> + Send + 'b,
         T: FromRow + Send + 'static;
 
     /// Exectues the given statement and returns the first row of the first result set.
+    ///
+    /// It'll prepare `stmt`, if necessary.
     fn exec_first<'a: 'b, 'b, T, S, P>(
         &'a mut self,
         stmt: &'b S,
@@ -195,6 +211,8 @@ pub trait Queryable: Send {
         T: FromRow + Send + 'static;
 
     /// Exectues the given stmt and folds the first result set to a signel value.
+    ///
+    /// It'll prepare `stmt`, if necessary.
     fn exec_map<'a: 'b, 'b, T, S, P, U, F>(
         &'a mut self,
         stmt: &'b S,
@@ -209,6 +227,8 @@ pub trait Queryable: Send {
         U: Send + 'a;
 
     /// Exectues the given stmt and folds the first result set to a signel value.
+    ///
+    /// It'll prepare `stmt`, if necessary.
     fn exec_fold<'a: 'b, 'b, T, S, P, U, F>(
         &'a mut self,
         stmt: &'b S,

src/queryable/query_result.rs

@@ -40,6 +40,10 @@ impl ResultSetMeta {
 }
 
 /// Result of a query or statement execution.
+///
+/// Represents an asyncronous query result, that may not be fully consumed. Note,
+/// that unconsumed query results are dropped implicitly when corresponding connection
+/// is dropped or queried.
 #[derive(Debug)]
 pub struct QueryResult<'a, 't: 'a, P> {
     conn: Connection<'a, 't>,
@@ -59,17 +63,15 @@ where
 
     /// Returns `true` if this query result may contain rows.
     ///
-    /// If `false` then there is no rows possible (e.g. result of an UPDATE query).
+    /// If `false` then no rows possible for this query tesult (e.g. result of an UPDATE query).
     fn has_rows(&self) -> bool {
         self.conn
             .get_pending_result()
             .and_then(|meta| meta.columns().map(|columns| columns.len() > 0).ok())
             .unwrap_or(false)
     }
 
-    /// `true` if there is no more rows nor result sets in this query.
-    ///
-    /// One could use it to check if there is more than one result set in this query result.
+    /// `true` if there are no more rows nor result sets in this query.
     pub fn is_empty(&self) -> bool {
         !self.has_rows() && !self.conn.more_results_exists()
     }
@@ -137,22 +139,22 @@ where
         self.conn.last_insert_id()
     }
 
-    /// Number of affected rows, as reported by the server, or `0`.
+    /// Number of affected rows as reported by the server, or `0`.
     pub fn affected_rows(&self) -> u64 {
         self.conn.affected_rows()
     }
 
-    /// Text information, as reported by the server, or an empty string.
+    /// Text information as reported by the server, or an empty string.
     pub fn info(&self) -> Cow<'_, str> {
         self.conn.info()
     }
 
-    /// Number of warnings, as reported by the server, or `0`.
+    /// Number of warnings as reported by the server, or `0`.
     pub fn warnings(&self) -> u16 {
         self.conn.get_warnings()
     }
 
-    /// Returns a future that collects result set of this query result.
+    /// Collects the current result set of this query result.
     ///
     /// It is parametrized by `R` and internally calls `R::from_row(Row)` on each row.
     ///
@@ -177,7 +179,7 @@ where
         .await
     }
 
-    /// Returns a future that collects result set of this query result.
+    /// Collects the current result set of this query result.
     ///
     /// It works the same way as [`QueryResult::collect`] but won't panic if row isn't convertible
     /// to `R`.
@@ -192,8 +194,7 @@ where
         .await
     }
 
-    /// Returns a future that collects the current result set of this query result and drops
-    /// everything else.
+    /// Collects the current result set of this query result and drops everything else.
     ///
     /// # Panic
     ///
@@ -209,8 +210,7 @@ where
         Ok(output)
     }
 
-    /// Returns a future that collects the current result set of this query result and drops
-    /// everything else.
+    /// Collects the current result set of this query result and drops everything else.
     ///
     /// It works the same way as [`QueryResult::collect_and_drop`] but won't panic if row isn't
     /// convertible to `R`.
@@ -223,7 +223,7 @@ where
         Ok(output)
     }
 
-    /// Returns a future that will execute `fun` on every row of the current result set.
+    /// Executes `fun` on every row of the current result set.
     ///
     /// It will stop on the nearest result set boundary (see `QueryResult::collect` docs).
     pub async fn for_each<F>(&mut self, mut fun: F) -> Result<()>
@@ -240,8 +240,7 @@ where
         }
     }
 
-    /// Returns a future that will execute `fun` on every row of the current result set and drop
-    /// everything else.
+    /// Executes `fun` on every row of the current result set and drops everything else.
     pub async fn for_each_and_drop<F>(mut self, fun: F) -> Result<()>
     where
         F: FnMut(Row),
@@ -251,7 +250,7 @@ where
         Ok(())
     }
 
-    /// Returns a future that will map every row of the current result set to `U` using `fun`.
+    /// Maps every row of the current result set to `U` using `fun`.
     ///
     /// It will stop on the nearest result set boundary (see `QueryResult::collect` docs).
     pub async fn map<F, U>(&mut self, mut fun: F) -> Result<Vec<U>>
@@ -265,8 +264,7 @@ where
         Ok(acc)
     }
 
-    /// Returns a future that will map every row of the current result set to `U` using `fun`
-    /// and drop everything else.
+    /// Map every row of the current result set to `U` using `fun` and drops everything else.
     pub async fn map_and_drop<F, U>(mut self, fun: F) -> Result<Vec<U>>
     where
         F: FnMut(Row) -> U,
@@ -276,7 +274,7 @@ where
         Ok(rows)
     }
 
-    /// Returns a future that will reduce rows of the current result set to `U` using `fun`.
+    /// Reduces rows of the current result set to `U` using `fun`.
     ///
     /// It will stop on the nearest result set boundary (see `QueryResult::collect` docs).
     pub async fn reduce<T, F, U>(&mut self, mut init: U, mut fun: F) -> Result<U>
@@ -290,8 +288,7 @@ where
         Ok(init)
     }
 
-    /// Returns a future that will reduce rows of the current result set to `U` using `fun` and drop
-    /// everything else.
+    /// Reduces rows of the current result set to `U` using `fun` and drops everything else.
     pub async fn reduce_and_drop<T, F, U>(mut self, init: U, fun: F) -> Result<U>
     where
         F: FnMut(U, T) -> U,
@@ -302,7 +299,7 @@ where
         Ok(acc)
     }
 
-    /// Returns a future that will drop this query result.
+    /// Drops this query result.
     pub async fn drop_result(mut self) -> Result<()> {
         loop {
             while let Some(_) = self.next().await? {}
@@ -314,7 +311,7 @@ where
 
     /// Returns a reference to a columns list of this query result.
     ///
-    /// Empty list means, that this result set was never meant to contain rows.
+    /// Empty list means that this result set was never meant to contain rows.
     pub fn columns_ref(&self) -> &[Column] {
         self.conn
             .get_pending_result()

src/queryable/stmt.rs

@@ -125,6 +125,8 @@ impl StmtInner {
 }
 
 /// Prepared statement.
+///
+/// Statement is only valid for connection with id `Statement::connection_id()`.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct Statement {
     pub(crate) inner: Arc<StmtInner>,
@@ -139,26 +141,32 @@ impl Statement {
         }
     }
 
+    /// Returned columns.
     pub fn columns(&self) -> &[Column] {
         self.inner.columns()
     }
 
+    /// Requred parameters.
     pub fn params(&self) -> &[Column] {
         self.inner.params()
     }
 
+    /// MySql statement identifier.
     pub fn id(&self) -> u32 {
         self.inner.id()
     }
 
+    /// MySql connection identifier.
     pub fn connection_id(&self) -> u32 {
         self.inner.connection_id()
     }
 
+    /// Number of parameters.
     pub fn num_params(&self) -> u16 {
         self.inner.num_params()
     }
 
+    /// Number of columns.
     pub fn num_columns(&self) -> u16 {
         self.inner.num_columns()
     }