From 4d9220bb7b716289810baa77f0c779abbd1b1485 Mon Sep 17 00:00:00 2001
From: Georg Semmler <github@weiznich.de>
Date: Fri, 26 Jan 2024 12:26:23 +0100
Subject: [PATCH] Finally fix the doc test

---
 diesel_derives/src/lib.rs | 74 ++++++++++++++++++++++++++++++++-------
 1 file changed, 61 insertions(+), 13 deletions(-)

diff --git a/diesel_derives/src/lib.rs b/diesel_derives/src/lib.rs
index e6ef0077b12c..9714a97fd9d5 100644
--- a/diesel_derives/src/lib.rs
+++ b/diesel_derives/src/lib.rs
@@ -1632,47 +1632,95 @@ pub fn table_proc(input: TokenStream) -> TokenStream {
 /// Support for additional types can be added by providing manual implementations of
 /// `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:
+/// For example to support a custom enum `MyEnum` with the custom SQL type `MyInteger`:
 /// ```
-/// # #[cfg(all(feature = "sqlite", feature = "time"))]
-/// # fn main() {
+/// extern crate diesel;
 /// use diesel::backend::Backend;
-/// use diesel::deserialize::{self, FromSql};
+/// use diesel::deserialize::{self, FromSql, FromSqlRow};
 /// use diesel::serialize::{self, IsNull, ToSql};
-/// use diesel::sql_types::HasSqlType;
+/// use diesel::AsExpression;
+/// use diesel::sql_types::{HasSqlType, SqlType};
+/// use diesel::prelude::*;
 ///
 /// #[derive(diesel::MultiConnection)]
 /// pub enum AnyConnection {
+/// #   #[cfg(feature = "postgres")]
+///     Postgresql(diesel::PgConnection),
+/// #   #[cfg(feature = "mysql")]
+///     Mysql(diesel::MysqlConnection),
+/// #   #[cfg(feature = "sqlite")]
 ///     Sqlite(diesel::SqliteConnection),
 /// }
 ///
+/// // defining an custom SQL type is optional
+/// // you can also use types from `diesel::sql_types`
+/// #[derive(Copy, Clone, Debug, SqlType)]
+/// #[diesel(postgres_type(name = "Int4"))]
+/// #[diesel(mysql_type(name = "Integer"))]
+/// #[diesel(sqlite_type(name = "Integer"))]
+/// struct MyInteger;
+///
+///
+/// // our custom enum
+/// #[repr(i32)]
+/// #[derive(Debug, Clone, Copy, AsExpression, FromSqlRow)]
+/// #[diesel(sql_type = MyInteger)]
+/// pub enum MyEnum {
+///     A = 1,
+///     B = 2,
+/// }
+///
 /// // The `MultiBackend` type is generated by `#[derive(diesel::MultiConnection)]`
-/// impl HasSqlType<diesel::sql_types::TimestamptzSqlite> for MultiBackend {
+/// // This part is only required if you define a custom sql type
+/// impl HasSqlType<MyInteger> 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)
+///        MultiBackend::lookup_sql_type::<MyInteger>(lookup)
 ///    }
 /// }
 ///
-/// impl FromSql<diesel::sql_types::TimestamptzSqlite, MultiBackend> for time::OffsetDateTime {
+/// impl FromSql<MyInteger, MultiBackend> for MyEnum {
 ///    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>()
+///        // This requires a `FromSql` impl for each backend
+///        bytes.from_sql::<MyEnum, MyInteger>()
 ///    }
 /// }
 ///
-/// impl ToSql<diesel::sql_types::TimestamptzSqlite, MultiBackend> for time::OffsetDateTime {
+/// impl ToSql<MyInteger, MultiBackend> for MyEnum {
 ///    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));
+///        /// This requires a `ToSql` impl for each backend
+///        out.set_value((MyInteger, self));
 ///        Ok(IsNull::No)
 ///    }
 /// }
+/// # #[cfg(feature = "postgres")]
+/// # impl ToSql<MyInteger, diesel::pg::Pg> for MyEnum {
+/// #    fn to_sql<'b>(&'b self, out: &mut serialize::Output<'b, '_, diesel::pg::Pg>) -> serialize::Result { todo!() }
+/// # }
+/// # #[cfg(feature = "mysql")]
+/// # impl ToSql<MyInteger, diesel::mysql::Mysql> for MyEnum {
+/// #    fn to_sql<'b>(&'b self, out: &mut serialize::Output<'b, '_, diesel::mysql::Mysql>) -> serialize::Result { todo!() }
+/// # }
+/// # #[cfg(feature = "sqlite")]
+/// # impl ToSql<MyInteger, diesel::sqlite::Sqlite> for MyEnum {
+/// #    fn to_sql<'b>(&'b self, out: &mut serialize::Output<'b, '_, diesel::sqlite::Sqlite>) -> serialize::Result { todo!() }
+/// # }
+/// # #[cfg(feature = "postgres")]
+/// # impl FromSql<MyInteger, diesel::pg::Pg> for MyEnum {
+/// #    fn from_sql(bytes: <diesel::pg::Pg as Backend>::RawValue<'_>) -> deserialize::Result<Self> { todo!() }
+/// # }
+/// # #[cfg(feature = "mysql")]
+/// # impl FromSql<MyInteger, diesel::mysql::Mysql> for MyEnum {
+/// #    fn from_sql(bytes: <diesel::mysql::Mysql as Backend>::RawValue<'_>) -> deserialize::Result<Self> { todo!() }
+/// # }
+/// # #[cfg(feature = "sqlite")]
+/// # impl FromSql<MyInteger, diesel::sqlite::Sqlite> for MyEnum {
+/// #    fn from_sql(bytes: <diesel::sqlite::Sqlite as Backend>::RawValue<'_>) -> deserialize::Result<Self> { todo!() }
 /// # }
-///
-/// # #[cfg(not(all(feature = "sqlite", feature = "time")))]
 /// # fn main() {}
 /// ```
 #[proc_macro_derive(MultiConnection)]