Add documentation and improve the implementation of the

`AsyncConnection::test_transaction` function

Author: weiznich

src/lib.rs

@@ -257,28 +257,63 @@ pub trait AsyncConnection: SimpleAsyncConnection + Sized + Send {
         Ok(())
     }
 
-    #[doc(hidden)]
-    fn test_transaction<'a, R, E, F>(&'a mut self, f: F) -> ScopedBoxFuture<'a, 'a, R>
+    /// Executes the given function inside a transaction, but does not commit
+    /// it. Panics if the given function returns an error.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # include!("doctest_setup.rs");
+    /// use diesel::result::Error;
+    /// use scoped_futures::ScopedFutureExt;
+    ///
+    /// # #[tokio::main(flavor = "current_thread")]
+    /// # async fn main() {
+    /// #     run_test().await.unwrap();
+    /// # }
+    /// #
+    /// # async fn run_test() -> QueryResult<()> {
+    /// #     use schema::users::dsl::*;
+    /// #     let conn = &mut establish_connection().await;
+    /// conn.test_transaction::<_, Error, _>(|conn| async move {
+    ///     diesel::insert_into(users)
+    ///         .values(name.eq("Ruby"))
+    ///         .execute(conn)
+    ///         .await?;
+    ///
+    ///     let all_names = users.select(name).load::<String>(conn).await?;
+    ///     assert_eq!(vec!["Sean", "Tess", "Ruby"], all_names);
+    ///
+    ///     Ok(())
+    /// }.scope_boxed()).await;
+    ///
+    /// // Even though we returned `Ok`, the transaction wasn't committed.
+    /// let all_names = users.select(name).load::<String>(conn).await?;
+    /// assert_eq!(vec!["Sean", "Tess"], all_names);
+    /// #     Ok(())
+    /// # }
+    /// ```
+    async fn test_transaction<'a, R, E, F>(&'a mut self, f: F) -> R
     where
         F: for<'r> FnOnce(&'r mut Self) -> ScopedBoxFuture<'a, 'r, Result<R, E>> + Send + 'a,
         E: Debug + Send + 'a,
         R: Send + 'a,
         Self: 'a,
     {
-        async move {
-            self.transaction::<R, _, _>(|c| {
-                async move {
-                    match f(c).await {
-                        Ok(t) => Ok(t),
-                        Err(_) => Err(Error::RollbackTransaction),
-                    }
-                }
-                .scope_boxed()
+        use futures_util::TryFutureExt;
+
+        let mut user_result = None;
+        let _ = self
+            .transaction::<R, _, _>(|c| {
+                f(c).map_err(|_| Error::RollbackTransaction)
+                    .and_then(|r| {
+                        user_result = Some(r);
+                        futures_util::future::ready(Err(Error::RollbackTransaction))
+                    })
+                    .scope_boxed()
             })
-            .await
-            .expect("Test Transaction did not succeed")
-        }
-        .scope_boxed()
+            .await;
+        user_result.expect("Transaction did not succeed")
     }
 
     #[doc(hidden)]