Add documentation to diesel's r2d2 module on what happens when

connections fail inside a pool

fix docstring

Author: chusteven

diesel/src/r2d2.rs

@@ -1,6 +1,20 @@
 //! 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::*;