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

Code before:
/// ```ignore
/// #[declare_sql_function]
/// extern "SQL" {
///     #[sql_name = "foo"]
///     fn foo_0<A>(a: A) -> Text;
///
///     #[sql_name = "foo"]
///     fn foo_1<A, B1, C1>(a: A, b_1: B1, c_1: C1) -> Text;
///
///     #[sql_name = "foo"]
///     fn foo_2<A, B1, C1, B2, C2>(a: A, b_1: B1, c_1: C1, b_2: B2, c_2: C2) -> Text;
///
///     ...
/// }
/// ```
///
/// ### Controlling the generation of variadic function variants
///
/// By default, only variants with 0, 1, and 2 repetitions of variadic arguments are generated. To
/// generate more variants, set the `DIESEL_VARIADIC_FUNCTION_ARGS` environment variable to the
/// desired number of variants.
#[proc_macro_attribute]
pub fn declare_sql_function(
    _attr: proc_macro::TokenStream,
    input: proc_macro::TokenStream,
) -> proc_macro::TokenStream {
    let input = proc_macro2::TokenStream::from(input);
    let result = syn::parse2::<ExternSqlBlock>(input.clone())
        .map(|res| sql_function::expand(res.function_decls, false).tokens);
    match result {
        Ok(token_stream) => token_stream.into(),
        Err(e) => {
            let mut output = input;
            output.extend(e.into_compile_error());
            output.into()
        }
    }
}

/// Declare a sql function for use in your code.
///
/// This macro works like [`declare_sql_function`], but also generates type aliases to simplify
/// working with the return types of the functions created by [`declare_sql_function`].
///
/// All generated type aliases are available in the `return_type_helpers` module:
///
/// ```rust
/// # extern crate diesel;
/// # use diesel::expression::functions::declare_sql_function_and_return_type_helpers;
/// # use diesel::sql_types::*;
/// #

Review comment (suggestion):
Can we link to [the cargo documentation](https://doc.rust-lang.org/cargo/reference/config.html#env) here + mention that this can be done through a `.cargo/config.toml` file (and possible also mention that this is different to `Cargo.toml`)

Code after:
/// }
/// ```
///
/// Which will be equivalent to
///
/// ```ignore
/// #[declare_sql_function]
/// extern "SQL" {
///     #[sql_name = "foo"]
///     fn foo_0<A>(a: A) -> Text;
///
///     #[sql_name = "foo"]
///     fn foo_1<A, B1, C1>(a: A, b_1: B1, c_1: C1) -> Text;
///
///     #[sql_name = "foo"]
///     fn foo_2<A, B1, C1, B2, C2>(a: A, b_1: B1, c_1: C1, b_2: B2, c_2: C2) -> Text;
///
///     ...
/// }
/// ```
///
/// ### Controlling the generation of variadic function variants
///
/// By default, only variants with 0, 1, and 2 repetitions of variadic arguments are generated. To
/// generate more variants, set the `DIESEL_VARIADIC_FUNCTION_ARGS` environment variable to the
/// desired number of variants.
///
/// For a greater convenience this environment variable can also be set in a `.cargo/config.toml`
/// file as described in the [cargo documentation](https://doc.rust-lang.org/cargo/reference/config.html#env).
///
/// ## Helper types generation
///
/// When the `generate_return_type_helpers` attribute is specified, for each function defined inside
/// an `extern "SQL"` block, a return type alias with the same name as the function is created and
/// placed in the `return_type_helpers` module:
///
/// ```rust
/// # extern crate diesel;
/// # use diesel::expression::functions::declare_sql_function;
/// # use diesel::sql_types::*;
/// #
/// # fn main() {
/// #   // Without the main function this code will be wrapped in the auto-generated
/// #   // `main` function and `#[declare_sql_function]` won't work properly.
/// # }
/// #
/// #[declare_sql_function(generate_return_type_helpers = true)]
/// extern "SQL" {
///     fn f<V: SqlType + SingleValue>(arg: V);
/// }
///