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

Code before:
/// For SQLite, specify which variant of `SqliteType` should be used
/// by adding `#[diesel(sqlite_type(name = "Variant"))]`.
///
/// # Attributes
///
/// ## Type attributes
///
/// * `#[diesel(postgres_type(name = "TypeName", schema = "public"))]` specifies support for
///   a postgresql type with the name `TypeName` in the schema `public`. Prefer this variant
///   for types with no stable OID (== everything but the builtin types). It is possible to leaf
///   of the `schema` part. In that case, Diesel defaults to the default postgres search path.
/// * `#[diesel(postgres_type(oid = 42, array_oid = 142))]`, specifies support for a
///   postgresql type with the given `oid` and `array_oid`. This variant
///   should only be used with types that have a stable OID.
/// * `#[diesel(sqlite_type(name = "TypeName"))]`, specifies support for a sqlite type
///   with the given name. `TypeName` needs to be one of the possible values
///   in `SqliteType`
/// * `#[diesel(mysql_type(name = "TypeName"))]`, specifies support for a mysql type
///   with the given name. `TypeName` needs to be one of the possible values
///   in `MysqlType`
///
#[cfg_attr(docsrs, doc = "# Expanded Code")]
#[cfg_attr(
    all(docsrs, feature = "sqlite"),
    doc = r#"
### SQLite

<details>
<summary> Expanded Code </summary>
"#
)]
#[cfg_attr(all(docsrs, feature = "sqlite"), doc = include_str!(concat!(env!("OUT_DIR"), "/sql_type_sqlite.md")))]
#[cfg_attr(all(docsrs, feature = "sqlite"), doc = "</details>")]
#[cfg_attr(
    all(docsrs, feature = "postgres"),
    doc = r#"

### PostgreSQL

<details>
<summary> Expanded Code </summary>
"#
)]
#[cfg_attr(all(docsrs, feature = "postgres"), doc = include_str!(concat!(env!("OUT_DIR"), "/sql_type_postgres.md")))]
#[cfg_attr(all(docsrs, feature = "postgres"), doc = "</details>")]
#[cfg_attr(
    all(docsrs, feature = "mysql"),
    doc = r#"

### MySQL


Review comment (suggestion):
I can't imagine any other differentiation other than this. So, why don't we:

1. Add the `# Expanded Code` and `<details>` part in the md files.
2. Allow handling of sqlite, postgres etc... there?

That way, we can just `include_str!` and nothing else.

Please let me know if my suggestion doesn't work.

Code after:
/// and also it will accept the same syntax as the other macro.
///
/// The syntax for this macro is very similar to that of a normal Rust function,
/// except the argument and return types will be the SQL types being used.
/// Typically, these types will come from [`diesel::sql_types`](../diesel/sql_types/index.html)
///
/// This macro will generate two items. A function with the name that you've
/// given, and a module with a helper type representing the return type of your
/// function. For example, this invocation:
///
/// ```ignore
/// define_sql_function!(fn lower(x: Text) -> Text);
/// ```
///
/// will generate this code:
///
/// ```ignore
/// pub fn lower<X>(x: X) -> lower<X> {
///     ...
/// }
///
/// pub type lower<X> = ...;
/// ```
///
/// Most attributes given to this macro will be put on the generated function
/// (including doc comments).
///
/// # Adding Doc Comments
///
/// ```no_run
/// # extern crate diesel;
/// # use diesel::*;
/// #
/// # table! { crates { id -> Integer, name -> VarChar, } }
/// #
/// use diesel::sql_types::Text;
///
/// define_sql_function! {
///     /// Represents the `canon_crate_name` SQL function, created in
///     /// migration ....
///     fn canon_crate_name(a: Text) -> Text;
/// }
///
/// # fn main() {
/// # use self::crates::dsl::*;
/// let target_name = "diesel";
/// crates.filter(canon_crate_name(name).eq(canon_crate_name(target_name)));
/// // This will generate the following SQL
/// // SELECT * FROM crates WHERE canon_crate_name(crates.name) = canon_crate_name($1)
/// # }
/// ```