Add documentation to diesel's r2d2 module on what happens when
connections fail inside a pool
fix docstring
//! Connection pooling via r2d2.
//!
//! Note: This module requires enabling the `r2d2` feature
+//!
+//! When used inside a pool, if an individual connection becomes
+//! broken (as determined by the [R2D2Connection::is_broken] method)
+//! then `r2d2` will put close and return the connection to the DB.
+//!
+//! `diesel` determines broken connections by whether or not the current
+//! thread is panicking or if individual `Connection` structs are
+//! broken (determined by the `is_broken()` method). Generically, these
+//! are left to individual backends to implement themselves.
+//!
+//! For SQLite, PG, and MySQL backends, specifically, `is_broken()`
+//! is determined by whether or not the `TransactionManagerStatus` (as a part
+//! of the `AnsiTransactionManager` struct) is in an `InError` state.
+//!
pub use r2d2::*;
