Include more detail for implementing custom types for diesel::MultiCo…

…nnection

diesel_derives/src/lib.rs

@@ -1630,8 +1630,43 @@ pub fn table_proc(input: TokenStream) -> TokenStream {
 /// * `diesel::sql_types::Timestamp`
 ///
 /// Support for additional types can be added by providing manual implementations of
-/// `HasSqlType`, `FromSql` and `ToSql` for the corresponding type + the generated
-/// database backend.
+/// `HasSqlType`, `FromSql` and `ToSql` for the corresponding type, all databases included
+/// in your enum, and the backend generated by this derive called MultiBackend.
+/// For example to support `diesel::sql_types::TimestamptzSqlite` with the `time` crate:
+/// ```
+/// use diesel::backend::Backend;
+/// use diesel::deserialize::{self, FromSql};
+/// use diesel::serialize::{self, IsNull, ToSql};
+/// use diesel::sql_types::HasSqlType;
+///
+/// #[derive(diesel::MultiConnection)]
+/// pub enum AnyConnection {
+/// #   #[cfg(feature = "sqlite")]
+///     Sqlite(diesel::SqliteConnection),
+/// }
+///
+/// #   #[cfg(all("sqlite", "time"))]
+/// impl HasSqlType<diesel::sql_types::TimestamptzSqlite> for MultiBackend {
+///    fn metadata(lookup: &mut Self::MetadataLookup) -> Self::TypeMetadata {
+///        MultiBackend::lookup_sql_type::<diesel::sql_types::TimestamptzSqlite>(lookup)
+///    }
+/// }
+///
+/// #   #[cfg(all("sqlite", "time"))]
+/// impl FromSql<diesel::sql_types::TimestamptzSqlite, MultiBackend> for time::OffsetDateTime {
+///    fn from_sql(bytes: <MultiBackend as Backend>::RawValue<'_>) -> deserialize::Result<Self> {
+///        bytes.from_sql::<time::OffsetDateTime, diesel::sql_types::TimestamptzSqlite>()
+///    }
+/// }
+///
+/// #   #[cfg(all("sqlite", "time"))]
+/// impl ToSql<diesel::sql_types::TimestamptzSqlite, MultiBackend> for time::OffsetDateTime {
+///    fn to_sql<'b>(&'b self, out: &mut serialize::Output<'b, '_, MultiBackend>) -> serialize::Result {
+///        out.set_value((diesel::sql_types::TimestamptzSqlite, self));
+///        Ok(IsNull::No)
+///    }
+/// }
+/// ```
 #[proc_macro_derive(MultiConnection)]
 pub fn derive_multiconnection(input: TokenStream) -> TokenStream {
     multiconnection::derive(syn::parse_macro_input!(input)).into()