Documentation improvements

Author: weiznich

Cargo.toml

@@ -28,11 +28,17 @@ chrono = "0.4"
 diesel = { version = "2.0.0-rc.1", default-features = false,  features = ["chrono"]}
 
 [features]
-default = ["postgres", "mysql", "deadpool", "bb8", "mobc"]
+default = []
 mysql = ["diesel/mysql_backend", "mysql_async", "mysql_common"]
 postgres = ["diesel/postgres_backend", "tokio-postgres", "tokio", "tokio/rt-multi-thread"]
 
 [[test]]
 name = "integration_tests"
 path = "tests/lib.rs"
 harness = true
+
+[package.metadata.docs.rs]
+features = ["postgres", "mysql", "deadpool", "bb8", "mobc"]
+no-default-features = true
+rustc-args = ["--cfg", "doc_cfg"]
+rustdoc-args = ["--cfg", "doc_cfg"]

src/lib.rs

@@ -1,3 +1,4 @@
+#![cfg_attr(doc_cfg, feature(doc_cfg, doc_auto_cfg))]
 //! Diesel-async provides async variants of diesel releated query functionality
 //!
 //! diesel-async is an extension to diesel itself. It is designed to be used togehter
@@ -71,20 +72,24 @@ use futures::{Future, Stream};
 #[cfg(feature = "mysql")]
 mod mysql;
 #[cfg(feature = "postgres")]
-mod pg;
+pub mod pg;
 #[cfg(any(feature = "deadpool", feature = "bb8", feature = "mobc"))]
 pub mod pooled_connection;
 mod run_query_dsl;
 mod stmt_cache;
 mod transaction_manager;
 
 #[cfg(feature = "mysql")]
+#[doc(inline)]
 pub use self::mysql::AsyncMysqlConnection;
 #[cfg(feature = "postgres")]
+#[doc(inline)]
 pub use self::pg::AsyncPgConnection;
+#[doc(inline)]
 pub use self::run_query_dsl::*;
 
-use self::transaction_manager::{AnsiTransactionManager, TransactionManager};
+#[doc(inline)]
+pub use self::transaction_manager::{AnsiTransactionManager, TransactionManager};
 
 /// Perform simple operations on a backend.
 ///
@@ -147,7 +152,7 @@ where
     /// If the transaction fails to commit due to a `SerializationFailure` or a
     /// `ReadOnlyTransaction` a rollback will be attempted.
     /// If the rollback fails, the error will be returned in a
-    /// [`Error::RollbackErrorOnCommit`](crate::result::Error::RollbackErrorOnCommit),
+    /// [`Error::RollbackErrorOnCommit`](diesel::result::Error::RollbackErrorOnCommit),
     /// from which you will be able to extract both the original commit error and
     /// the rollback error.
     /// In addition, the connection will be considered broken

src/pg/mod.rs

@@ -1,3 +1,9 @@
+//! Provides types and functions related to working with PostgreSQL
+//!
+//! Much of this module is re-exported from database agnostic locations.
+//! However, if you are writing code specifically to extend Diesel on
+//! PostgreSQL, you may need to work with this module directly.
+
 use self::error_helper::ErrorHelper;
 use self::row::PgRow;
 use self::serialize::ToSqlHelper;

src/pg/transaction_builder.rs

@@ -3,9 +3,19 @@ use diesel::pg::Pg;
 use diesel::query_builder::{AstPass, QueryBuilder, QueryFragment};
 use diesel::QueryResult;
 use futures::future::BoxFuture;
-
 use crate::{AnsiTransactionManager, AsyncConnection, TransactionManager};
 
+/// Used to build a transaction, specifying additional details.
+///
+/// This struct is returned by [`AsyncPgConnection::build_transaction`].
+/// See the documentation for methods on this struct for usage examples.
+/// See [the PostgreSQL documentation for `SET TRANSACTION`][pg-docs]
+/// for details on the behavior of each option.
+///
+/// [`AsyncPgConnection::build_transaction`]: super::AsyncPgConnection::build_transaction()
+/// [pg-docs]: https://www.postgresql.org/docs/current/static/sql-set-transaction.html
+#[must_use = "Transaction builder does nothing unless you call `run` on it"]
+#[cfg(feature = "postgres")]
 pub struct TransactionBuilder<'a, C> {
     connection: &'a mut C,
     isolation_level: Option<IsolationLevel>,

src/run_query_dsl/mod.rs

@@ -171,7 +171,8 @@ pub mod return_futures {
     use diesel::QueryResult;
     use std::pin::Pin;
 
-    /// The future returned by [`RunQueryDsl::load`] and [`RunQueryDsl::get_results`]
+    /// The future returned by [`RunQueryDsl::load`](super::RunQueryDsl::load)
+    /// and [`RunQueryDsl::get_results`](super::RunQueryDsl::get_results)
     ///
     /// This is essentially `impl Future<Output = QueryResult<Vec<U>>>`
     pub type LoadFuture<'conn, 'query, Q, Conn, U> = futures::future::AndThen<
@@ -188,7 +189,7 @@ pub mod return_futures {
         >,
     >;
 
-    /// The future returned by [`RunQueryDsl::get_results`]
+    /// The future returned by [`RunQueryDsl::get_result`](super::RunQueryDsl::get_result)
     ///
     /// This is essentially `impl Future<Output = QueryResult<U>>`
     pub type GetResult<'conn, 'query, Q, Conn, U> = futures::future::AndThen<
@@ -223,7 +224,7 @@ pub mod return_futures {
         >,
     >;
 
-    /// The future returned by [`RunQueryDsl::execute`]
+    /// The future returned by [`RunQueryDsl::execute`](super::RunQueryDsl::execute)
     ///
     /// This is essentially `impl Future<Output = QueryResult<usize>>`
     pub type Execute<'conn, 'query, Conn> = <Conn as AsyncConnectionGatWorkaround<

src/transaction_manager.rs

@@ -49,7 +49,7 @@ pub trait TransactionManager<Conn: AsyncConnection>: Send {
     /// Executes the given function inside of a database transaction
     ///
     /// Each implementation of this function needs to fulfill the documented
-    /// behaviour of [`Connection::transaction`]
+    /// behaviour of [`AsyncConnection::transaction`]
     async fn transaction<F, R, E>(conn: &mut Conn, callback: F) -> Result<R, E>
     where
         F: FnOnce(&mut Conn) -> BoxFuture<Result<R, E>> + Send,