Repository: diesel-rs/diesel
File: diesel/src/serialize.rs (Rust)

Code before:
/// # use diesel::serialize::{self, ToSql, Output, IsNull};
/// # use std::io::Write;
/// #
/// pub mod sql_types {
///    #[derive(diesel::sql_types::SqlType)]
///    #[diesel(mysql_type(name = "Enum"))]
///    pub struct PostEnum; //<- generated by diesel cli
/// }
/// #[derive(Debug, AsExpression, PartialEq, Clone)]
/// #[diesel(sql_type = sql_types::PostEnum)]
/// pub enum Post {
///    FirstValue,
///    SecondValue,
/// }
///
/// # #[cfg(feature = "mysql")]
/// impl ToSql<sql_types::PostEnum, diesel::mysql::Mysql> for Post {
///    fn to_sql<'b>(&'b self, out: &mut Output<'b, '_, diesel::mysql::Mysql>) -> serialize::Result {
///        match *self {
///            Post::FirstValue => out.write_all(b"one")?,
///            Post::SecondValue => out.write_all(b"two")?,
///        }
///        Ok(IsNull::No)
///    }
/// }
/// ```
///
/// Using temporary values as part of the `ToSql` implementation requires additional
/// work.
///
/// Backends using [`RawBytesBindCollector`] as [`BindCollector`] copy the serialized values as part
/// of `Write` implementation. This includes the `Mysql` and the `Pg` backend provided by diesel.
/// This means existing `ToSql` implementations can be used even with
/// temporary values. For these it is required to call
/// [`Output::reborrow`] to shorten the lifetime of the `Output` type correspondingly.
///
/// ```
/// # use diesel::backend::Backend;
/// # use diesel::expression::AsExpression;
/// # use diesel::sql_types::*;
/// # use diesel::serialize::{self, ToSql, Output};
/// # use std::io::Write;
/// #
/// #[repr(i32)]
/// #[derive(Debug, Clone, Copy, AsExpression)]
/// #[diesel(sql_type = Integer)]
/// pub enum MyEnum {
///     A = 1,
///     B = 2,
/// }
///

Review comment (suggestion):
```suggestion
///            // these string values need to match the labels used in your
///            // enum definition in SQL. So this expects that you defined the 
///            /// relevat enum type as`ENUM('one', 'two')` in your `CREATE TABLE` statement
///            Post::FirstValue => out.write_all(b"one")?,
```

Code after:
/// # use diesel::expression::AsExpression;
/// # use diesel::sql_types::*;
/// # use diesel::serialize::{self, ToSql, Output, IsNull};
/// # use std::io::Write;
/// #
/// pub mod sql_types {
///    #[derive(diesel::sql_types::SqlType)]
///    #[diesel(mysql_type(name = "Enum"))]
///    pub struct PostEnum; //<- generated by diesel cli
/// }

/// #[derive(Debug, AsExpression, PartialEq, Clone)]
/// #[diesel(sql_type = sql_types::PostEnum)]
/// pub enum Post {
///    FirstValue,
///    SecondValue,
/// }
///
/// # #[cfg(feature = "mysql")]
/// impl ToSql<sql_types::PostEnum, diesel::mysql::Mysql> for Post {
///    fn to_sql<'b>(&'b self, out: &mut Output<'b, '_, diesel::mysql::Mysql>) -> serialize::Result {
///        match *self {
///            // these string values need to match the labels used in your
///            // enum definition in SQL. So this expects that you defined the
///            /// relevat enum type as`ENUM('one', 'two')` in your `CREATE TABLE` statement
///            Post::FirstValue => out.write_all(b"one")?,
///            Post::SecondValue => out.write_all(b"two")?,
///        }
///        Ok(IsNull::No)
///    }
/// }
/// ```
///
/// Using temporary values as part of the `ToSql` implementation requires additional
/// work.
///
/// Backends using [`RawBytesBindCollector`] as [`BindCollector`] copy the serialized values as part
/// of `Write` implementation. This includes the `Mysql` and the `Pg` backend provided by diesel.
/// This means existing `ToSql` implementations can be used even with
/// temporary values. For these it is required to call
/// [`Output::reborrow`] to shorten the lifetime of the `Output` type correspondingly.
///
/// ```
/// # use diesel::backend::Backend;
/// # use diesel::expression::AsExpression;
/// # use diesel::sql_types::*;
/// # use diesel::serialize::{self, ToSql, Output};
/// # use std::io::Write;
/// #
/// #[repr(i32)]
/// #[derive(Debug, Clone, Copy, AsExpression)]