docs: polish, add some information on supported databases and runtimes

sqlx-core/src/blocking.rs

@@ -1,4 +1,5 @@
-//! Types and traits used to implement a database driver with **blocking** I/O.
+//! Types and traits used to interact with a database driver
+//! for **blocking** operations.
 //!
 
 use std::io::{Read, Result as IoResult, Write};
@@ -21,44 +22,60 @@ pub use connection::Connection;
 pub use options::ConnectOptions;
 pub use runtime::Runtime;
 
+/// Convenience re-export of common traits for blocking operations.
 pub mod prelude {
-    pub use super::Acquire;
-    pub use super::Close;
-    pub use super::Connect;
-    pub use super::ConnectOptions;
-    pub use super::Connection;
-    pub use super::Runtime;
-    pub use crate::Database;
+    #[doc(no_inline)]
+    pub use super::Acquire as _;
+    #[doc(no_inline)]
+    pub use super::Close as _;
+    #[doc(no_inline)]
+    pub use super::Connect as _;
+    #[doc(no_inline)]
+    pub use super::ConnectOptions as _;
+    #[doc(no_inline)]
+    pub use super::Connection as _;
+    #[doc(no_inline)]
+    pub use super::Runtime as _;
+    #[doc(no_inline)]
+    pub use crate::Database as _;
 }
 
-/// Uses the `std::net` primitives to implement a blocking runtime for SQLx.
-#[derive(Debug)]
-pub struct Blocking;
+pub(super) mod rt {
+    /// Uses the `std::net` primitives to implement a blocking runtime for SQLx.
+    #[derive(Debug)]
+    pub struct Blocking;
+}
 
-impl crate::Runtime for Blocking {
+impl crate::Runtime for rt::Blocking {
+    #[doc(hidden)]
     type TcpStream = TcpStream;
 }
 
-impl Runtime for Blocking {
+impl Runtime for rt::Blocking {
+    #[doc(hidden)]
     fn connect_tcp(host: &str, port: u16) -> IoResult<Self::TcpStream> {
         TcpStream::connect((host, port))
     }
 }
 
 // 's: stream
-impl<'s> crate::io::Stream<'s, Blocking> for TcpStream {
+impl<'s> crate::io::Stream<'s, rt::Blocking> for TcpStream {
+    #[doc(hidden)]
     #[cfg(feature = "async")]
     type ReadFuture = futures_util::future::BoxFuture<'s, IoResult<usize>>;
 
+    #[doc(hidden)]
     #[cfg(feature = "async")]
     type WriteFuture = futures_util::future::BoxFuture<'s, IoResult<usize>>;
 
+    #[doc(hidden)]
     #[cfg(feature = "async")]
     fn read_async(&'s mut self, _buf: &'s mut [u8]) -> Self::ReadFuture {
         // UNREACHABLE: [`Blocking`] does not implement the [`Async`] marker
         unreachable!()
     }
 
+    #[doc(hidden)]
     #[cfg(feature = "async")]
     fn write_async(&'s mut self, _buf: &'s [u8]) -> Self::WriteFuture {
         // UNREACHABLE: [`Blocking`] does not implement the [`Async`] marker
@@ -67,11 +84,13 @@ impl<'s> crate::io::Stream<'s, Blocking> for TcpStream {
 }
 
 // 's: stream
-impl<'s> io::Stream<'s, Blocking> for TcpStream {
+impl<'s> io::Stream<'s, rt::Blocking> for TcpStream {
+    #[doc(hidden)]
     fn read(&'s mut self, buf: &'s mut [u8]) -> IoResult<usize> {
         Read::read(self, buf)
     }
 
+    #[doc(hidden)]
     fn write(&'s mut self, buf: &'s [u8]) -> IoResult<usize> {
         let size = buf.len();
         self.write_all(buf)?;

sqlx-core/src/lib.rs

@@ -39,7 +39,7 @@ pub mod blocking;
 
 pub use acquire::Acquire;
 #[cfg(feature = "blocking")]
-pub use blocking::Blocking;
+pub use blocking::rt::Blocking;
 pub use close::Close;
 pub use connect::Connect;
 pub use connection::Connection;
@@ -55,15 +55,22 @@ pub use runtime::AsyncStd;
 pub use runtime::Tokio;
 pub use runtime::{Async, DefaultRuntime, Runtime};
 
-#[cfg(any(feature = "async-std", feature = "tokio", feature = "actix"))]
+/// Convenience re-export of common traits for non-blocking operations.
 pub mod prelude {
-    pub use super::Acquire;
-    pub use super::Close;
-    pub use super::Connect;
-    pub use super::ConnectOptions;
-    pub use super::Connection;
-    pub use super::Database;
-    pub use super::Runtime;
+    #[doc(no_inline)]
+    pub use super::Acquire as _;
+    #[doc(no_inline)]
+    pub use super::Close as _;
+    #[doc(no_inline)]
+    pub use super::Connect as _;
+    #[doc(no_inline)]
+    pub use super::ConnectOptions as _;
+    #[doc(no_inline)]
+    pub use super::Connection as _;
+    #[doc(no_inline)]
+    pub use super::Database as _;
+    #[doc(no_inline)]
+    pub use super::Runtime as _;
 }
 
 #[cfg(all(
@@ -71,11 +78,3 @@ pub mod prelude {
     feature = "blocking"
 ))]
 pub use blocking::prelude;
-
-#[cfg(not(any(
-    feature = "async-std",
-    feature = "actix",
-    feature = "tokio",
-    feature = "blocking"
-)))]
-pub mod prelude {}

sqlx-core/src/runtime.rs

@@ -39,7 +39,7 @@ pub use tokio_::Tokio;
 /// Additionally, a `std` blocking runtime is provided. This is intended for use in
 /// environments where asynchronous IO either doesn't make sense or isn't available.
 ///
-/// -   [`Blocking`][crate::blocking::Blocking]
+/// -   [`Blocking`][crate::Blocking]
 ///
 pub trait Runtime: 'static + Send + Sync + Sized {
     #[doc(hidden)]
@@ -119,7 +119,7 @@ mod default {
 /// 1.   [`AsyncStd`]
 /// 2.   [`Tokio`]
 /// 3.   [`Actix`]
-/// 4.   [`Blocking`]
+/// 4.   [`Blocking`][crate::Blocking]
 /// 5.   `()` – No runtime selected (nothing is possible)
 ///
 /// The intent is to allow the following to cleanly work, regardless of the enabled runtime,

sqlx-core/src/runtime/actix.rs

@@ -7,7 +7,7 @@ use futures_util::{future::BoxFuture, AsyncReadExt, AsyncWriteExt, FutureExt, Tr
 
 use crate::{io::Stream, Async, Runtime};
 
-/// Actix SQLx runtime. Uses [`actix-rt`][actix_rt] to provide [`Runtime`].
+/// Provides [`Runtime`] for [**Actix**](https://actix.rs). Supports only non-blocking operation.
 ///
 /// As of 2021 Jan., Actix re-exports Tokio so this should be equivalent to [`Tokio`][crate::Tokio].
 /// This is split-out to allow Actix to shift, or for it to use a different major Tokio version and

sqlx-core/src/runtime/async_std.rs

@@ -1,4 +1,6 @@
 use _async_std::net::TcpStream;
+#[cfg(feature = "blocking")]
+use _async_std::task;
 use futures_util::io::{Read, Write};
 use futures_util::{future::BoxFuture, AsyncReadExt, AsyncWriteExt, FutureExt};
 
@@ -6,11 +8,11 @@ use futures_util::{future::BoxFuture, AsyncReadExt, AsyncWriteExt, FutureExt};
 use crate::blocking;
 use crate::{io::Stream, Async, Runtime};
 
-/// Provides [`Runtime`] for [**async-std**][_async_std]. Supports both blocking
+/// Provides [`Runtime`] for [**async-std**](https://async.rs). Supports both blocking
 /// and non-blocking operation.
 ///
 /// For blocking operation, the equivalent non-blocking methods are called
-/// and trivially wrapped in [`task::block_on`][_async_std::task::block_on].
+/// and trivially wrapped in [`task::block_on`][task::block_on].
 ///
 #[cfg_attr(doc_cfg, doc(cfg(feature = "async-std")))]
 #[derive(Debug)]
@@ -30,8 +32,9 @@ impl Async for AsyncStd {
 
 #[cfg(feature = "blocking")]
 impl blocking::Runtime for AsyncStd {
+    #[doc(hidden)]
     fn connect_tcp(host: &str, port: u16) -> std::io::Result<Self::TcpStream> {
-        _async_std::task::block_on(Self::connect_tcp_async(host, port))
+        task::block_on(Self::connect_tcp_async(host, port))
     }
 }
 

sqlx-core/src/runtime/tokio.rs

@@ -7,7 +7,7 @@ use futures_util::{future::BoxFuture, AsyncReadExt, AsyncWriteExt, FutureExt, Tr
 
 use crate::{io::Stream, Async, Runtime};
 
-/// Tokio SQLx runtime. Uses [`tokio`] to provide [`Runtime`].
+/// Provides [`Runtime`] for [**Tokio**](https://tokio.rs). Supports only non-blocking operation.
 ///
 /// SQLx does not require the use of a multi-threaded executor.
 ///

sqlx-mysql/src/lib.rs

@@ -1,6 +1,6 @@
-//! [MySQL] database driver for [SQLx][sqlx_core], the Rust SQL toolkit.
+//! [**MySQL**] database driver.
 //!
-//! [MySQL]: https://www.mysql.com/
+//! [**MySQL**]: https://www.mysql.com/
 //!
 #![cfg_attr(doc_cfg, feature(doc_cfg))]
 #![cfg_attr(not(any(feature = "async", feature = "blocking")), allow(unused))]

sqlx/src/lib.rs

@@ -1,4 +1,31 @@
-//! SQLx is an async, pure Rust SQL crate featuring compile-time checked queries without a DSL.
+//! SQLx is an async-first, pure Rust SQL crate featuring compile-time checked queries without a DSL.
+//!
+//! ## Database
+//!
+//! SQLx is **database agnostic**. Functionality is composed through traits defined in `sqlx-core` and implemented
+//! in SQLx driver crates (`sqlx-postgres`, etc.). Enable support for a database by selecting an associated
+//! crate feature.
+//!
+//! | Database | Supported Versions | Crate feature | Driver module |
+//! | --- | --- | --- | --- |
+//! | [MySQL](https://www.mysql.com/) | 5.0+, 8.0 | `mysql` | [`mysql`][sqlx_mysql]
+//! | [MariaDB](https://mariadb.com/) | 10.2+ | `mysql` | [`mysql`][sqlx_mysql]
+//!
+//! ## Runtime
+//!
+//! SQLx is **asynchronous** (by default) and operation requires the selection of a runtime. This is done through
+//! selecting one of the below crate features.
+//!
+//! Additionally, there is a **blocking** runtime available for simple use cases or environments where
+//! asynchronous IO is either not available or not practical. The blocking runtime _does not wrap
+//! the asynchronous runtime_. Blocking versions of the core traits are available in the [`blocking`] module.
+//!
+//! | Crate feature | Runtime | Prelude |
+//! | --- | --- | --- |
+//! | `async-std` | [`AsyncStd`] | [`sqlx::prelude`][prelude] or [`sqlx::blocking::prelude`][blocking::prelude] |
+//! | `tokio` | [`Tokio`] | [`sqlx::prelude`][prelude]|
+//! | `actix` | [`Actix`] | [`sqlx::prelude`][prelude] |
+//! | `blocking` | [`Blocking`] | [`sqlx::blocking::prelude`][blocking::prelude] |
 //!
 #![deny(unsafe_code)]
 #![warn(rust_2018_idioms)]
@@ -15,16 +42,18 @@
 #![warn(clippy::useless_let_if_seq)]
 #![allow(clippy::doc_markdown)]
 
-#[cfg(feature = "blocking")]
-pub use sqlx_core::blocking;
 #[cfg(feature = "actix")]
 pub use sqlx_core::Actix;
 #[cfg(feature = "async-std")]
 pub use sqlx_core::AsyncStd;
 #[cfg(feature = "tokio")]
 pub use sqlx_core::Tokio;
+#[cfg(feature = "blocking")]
+pub use sqlx_core::{blocking, Blocking};
 pub use sqlx_core::{
-    prelude, ConnectOptions, Connection, Database, DefaultRuntime, Error, Result, Runtime,
+    prelude, Acquire, Close, Connect, ConnectOptions, Connection, Database, DefaultRuntime, Error,
+    Result, Runtime,
 };
 #[cfg(feature = "mysql")]
+#[doc(inline)]
 pub use sqlx_mysql as mysql;