Improve the documentation of our derives

[weiznich]

#4714 introduced expanded code examples for the derives provided by diesel CLI in our API documentation. See for example here

We would like to extend this documentation to include examples for all derive attributes supported by the various derives.

Steps to implement this:

1. Go to diesel_derives/src/tests/$derive.rs and add a new test example there as new test case. Eg. mirroring this test case:

   diesel/diesel_derives/src/tests/as_changeset.rs

   Lines 6 to 19 in 7a43396

   	pub(crate) fn as_changeset_1() {
   	let input = quote::quote! {
   	struct User {
   	id: i32,
   	name: String
   	}
   	};
   	expand_with(
   	&crate::derive_as_changeset_inner as &dyn Fn(_) -> _,
   	input,
   	derive(syn::parse_quote!(#[derive(AsChangeset)])),
   	"as_changeset_1",
   	);
   	}

   
   Make sure that the example includes the relevant attribute
2. Run cargo xtask run-tests all --no-doc-tests --no-example-schema-check -- -E 'package(diesel_derives) & test(#tests::*)' and accept the newly added snapshots via cargo insta
3. Verify that the output is the same for all backends. If this is not the case make sure to add different variants like done here

   diesel/diesel_derives/src/tests/has_query.rs

   Lines 13 to 27 in 7a43396

   	let name = if cfg!(feature = "sqlite") {
   	"has_query_1 (sqlite)"
   	} else if cfg!(feature = "postgres") {
   	"has_query_1 (postgres)"
   	} else if cfg!(feature = "mysql") {
   	"has_query_1 (mysql)"
   	} else {
   	unimplemented!()
   	};
   	expand_with(
   	&crate::derive_has_query_inner as &dyn Fn(_) -> _,
   	input,
   	derive(syn::parse_quote!(#[derive(HasQuery)])),
   	name,
   	);

4. Modify the build script here to include the new snapshot in the documentation: https://github.com/diesel-rs/diesel/blob/main/diesel_derives/build.rs#L116
5. Verify via RUSTFLAGS="--cfg diesel_docsrs" RUSTDOCFLAGS="--cfg diesel_docsrs" cargo +nightly doc -p diesel --open + opening the documentation the derive you are working on that the code is shown there

We still miss the following attributes:

#[derive(AsChangeset)]

Struct

• #[diesel(treat_none_as_null = true)]
• #[diesel(table_name = path::to::table)]]
• `#[diesel(primary_key(id1, id2))]]

Field

• #[diesel(column_name = some_column_name)]
• #[diesel(embed)]
• #[diesel(serialize_as = SomeType)]
• #[diesel(treat_none_as_null = true/false)]
• #[diesel(skip_update)]

#[derive(AsExpression)]

Type

• #[diesel(not_sized)]

#[derive(Associations)]

Type

• #[diesel(table_name = path::to::table)]

Field

• #[diesel(column_name = some_column_name)]

#[derive(HasQuery)]

Type

• #[diesel(base_query = _)]
• #[diesel(base_query_type = _)]
• #[diesel(table_name = path::to::table)]
• #[diesel(check_for_backend(diesel::pg::Pg, diesel::mysql::Mysql))]
• #[diesel(check_for_backend(disable = true))]

Fields

• #[diesel(column_name = some_column)]
• #[diesel(embed)]
• #[diesel(select_expression = some_custom_select_expression)]
• #[diesel(select_expression_type = the_custom_select_expression_type)]
• #[diesel(deserialize_as = Type)]

#[derive(Identifiable)]

Type

• #[diesel(table_name = path::to::table)]
• #[diesel(primary_key(id1, id2))]

Fields

• #[diesel(column_name = some_column_name)]

#[derive(Insertable)]

Type

• #[diesel(table_name = path::to::table)]
• #[diesel(treat_none_as_default_value = false)]

Fields

• #[diesel(column_name = some_column_name)]
• #[diesel(embed)]
• #[diesel(serialize_as = SomeType)]
• #[diesel(treat_none_as_default_value = true/false)]
• #[diesel(skip_insertion)]

#[derive(Queryable)]

Fields

• #[diesel(deserialize_as = Type)]

#[derive(QueryableByName)]

Type

• #[diesel(table_name = path::to::table)]
• #[diesel(check_for_backend(diesel::pg::Pg, diesel::mysql::Mysql))]

Fields

• #[diesel(column_name = some_column)]
• #[diesel(sql_type = SomeType)]
• #[diesel(deserialize_as = Type)]
• #[diesel(embed)]

#[derive(Selectable)]

Type

• #[diesel(check_for_backend(diesel::pg::Pg, diesel::mysql::Mysql))]

Field

• #[diesel(column_name = some_column)]
• #[diesel(embed)]
• #[diesel(select_expression = some_custom_select_expression)]
• #[diesel(select_expression_type = the_custom_select_expression_type]

#[derive(ValidGrouping)]

Type

• #[diesel(aggregate)]

#[declare_sql_function)]

• #[aggregate]
• #[sql_name = "name"]
• #[variadic(argument_count)]
• #[window]

Please ask questions if you have problems understanding how a specific attribute is meant to be used.

Please comment below this issue if you want to work on one of the attributes to organize the work between different persons.

[Venkat4real]

Hi, I found this issue through GitHub's advanced search. I am a novice technical writer. I want to contribute, but this looks complicated. But I'd still love to help with the docs in the diesel repo! If you have any guide writing, editing, or general cleanup tasks. Please let me know.

[valkrypton]

cargo doc -p diesel --open When I open the documentation with this command, I don't see the expanded code section

[weiznich]

@valkrypton Thanks for pointing that out. I've updated the OP to include the right command. For reference: You need to set a few additional flags like this RUSTFLAGS="--cfg diesel_docsrs" RUSTDOCFLAGS="--cfg diesel_docsrs" cargo +nightly doc -p diesel --open

@Venkat4real Thanks for your interest in contributing. I manged to miss your post before so sorry for the late answer. We have a separate repo for our website which features guides, etc here. I would be very grateful for any improvements there as well.