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

diesel_derives/src/lib.rs

@@ -1630,8 +1630,51 @@ 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:
+/// ```
+/// # #[cfg(all(feature = "sqlite", feature = "time"))]
+/// # fn main() {
+/// 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 {
+///     Sqlite(diesel::SqliteConnection),
+/// }
+///
+/// // The `MultiBackend` type is generated by `#[derive(diesel::MultiConnection)]`
+/// impl HasSqlType<diesel::sql_types::TimestamptzSqlite> for MultiBackend {
+///    fn metadata(lookup: &mut Self::MetadataLookup) -> Self::TypeMetadata {
+///        // The `lookup_sql_type` function is exposed by the `MultiBackend` type
+///        MultiBackend::lookup_sql_type::<diesel::sql_types::TimestamptzSqlite>(lookup)
+///    }
+/// }
+///
+/// impl FromSql<diesel::sql_types::TimestamptzSqlite, MultiBackend> for time::OffsetDateTime {
+///    fn from_sql(bytes: <MultiBackend as Backend>::RawValue<'_>) -> deserialize::Result<Self> {
+///        // The `from_sql` function is exposed by the `RawValue` type of the
+///        // `MultiBackend` type
+///        bytes.from_sql::<time::OffsetDateTime, diesel::sql_types::TimestamptzSqlite>()
+///    }
+/// }
+///
+/// impl ToSql<diesel::sql_types::TimestamptzSqlite, MultiBackend> for time::OffsetDateTime {
+///    fn to_sql<'b>(&'b self, out: &mut serialize::Output<'b, '_, MultiBackend>) -> serialize::Result {
+///        /// `set_value` expects a tuple consisting of the target SQL type
+///        /// and self for `MultiBackend`
+///        out.set_value((diesel::sql_types::TimestamptzSqlite, self));
+///        Ok(IsNull::No)
+///    }
+/// }
+/// # }
+///
+/// # #[cfg(not(all(feature = "sqlite", feature = "time")))]
+/// # fn main() {}
+/// ```
 #[proc_macro_derive(MultiConnection)]
 pub fn derive_multiconnection(input: TokenStream) -> TokenStream {
     multiconnection::derive(syn::parse_macro_input!(input)).into()