From 60392ed88243012e968a6baf69e92ffe055b7d51 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Tue, 9 Jan 2024 01:49:59 +0100 Subject: [PATCH 1/7] scylla: create macros module This will be required to move documentation of serialization macros into scylla crate. This in turn is required to workaround the issue that documentation for those macros is not rendered on docs.rs correctly. --- scylla/src/lib.rs | 4 +++- scylla/src/macros.rs | 11 +++++++++++ 2 files changed, 14 insertions(+), 1 deletion(-) create mode 100644 scylla/src/macros.rs diff --git a/scylla/src/lib.rs b/scylla/src/lib.rs index 5bf9bc69e8..11198c1c95 100644 --- a/scylla/src/lib.rs +++ b/scylla/src/lib.rs @@ -98,8 +98,10 @@ pub mod _macro_internal { pub use scylla_cql::_macro_internal::*; } +pub mod macros; +pub use macros::*; + pub use scylla_cql::frame; -pub use scylla_cql::macros::{self, *}; pub use scylla_cql::types::serialize; pub mod authentication; diff --git a/scylla/src/macros.rs b/scylla/src/macros.rs new file mode 100644 index 0000000000..00bc9bfef5 --- /dev/null +++ b/scylla/src/macros.rs @@ -0,0 +1,11 @@ +pub use scylla_cql::macros::FromRow; +pub use scylla_cql::macros::FromUserType; +pub use scylla_cql::macros::IntoUserType; +pub use scylla_cql::macros::SerializeCql; +pub use scylla_cql::macros::SerializeRow; +pub use scylla_cql::macros::ValueList; + +pub use scylla_cql::macros::impl_from_cql_value_from_method; + +// Reexports for derive(IntoUserType) +pub use bytes::{BufMut, Bytes, BytesMut}; From 4c154ba5c8ae57f503c51093a200c77b6ff2d508 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Tue, 9 Jan 2024 02:15:42 +0100 Subject: [PATCH 2/7] scylla-macros: Replace derive macros docs with stubs When both original item and re-export are documented, documentations are merged. Before this commit, both original item and re-export were documented - identically or at least very similarly. This caused docs in scylla-cql crate to be copy-pasted twice. Replace docs with stubs pointing to the scylla crate to avoid it and point users to proper documentation. --- scylla-macros/src/lib.rs | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/scylla-macros/src/lib.rs b/scylla-macros/src/lib.rs index 64ce0ee06e..cb8b967c84 100644 --- a/scylla-macros/src/lib.rs +++ b/scylla-macros/src/lib.rs @@ -9,7 +9,9 @@ mod value_list; mod serialize; -/// See the documentation for this item in the `scylla` crate. +/// Documentation for this macro can only be found +/// in `scylla` crate - not in scylla-macros nor in scylla-cql. +/// This is because of rustdocs limitations that are hard to explain here. #[proc_macro_derive(SerializeCql, attributes(scylla))] pub fn serialize_cql_derive(tokens_input: TokenStream) -> TokenStream { match serialize::cql::derive_serialize_cql(tokens_input) { @@ -18,7 +20,9 @@ pub fn serialize_cql_derive(tokens_input: TokenStream) -> TokenStream { } } -/// See the documentation for this item in the `scylla` crate. +/// Documentation for this macro can only be found +/// in `scylla` crate - not in scylla-macros nor in scylla-cql. +/// This is because of rustdocs limitations that are hard to explain here. #[proc_macro_derive(SerializeRow, attributes(scylla))] pub fn serialize_row_derive(tokens_input: TokenStream) -> TokenStream { match serialize::row::derive_serialize_row(tokens_input) { @@ -27,32 +31,36 @@ pub fn serialize_row_derive(tokens_input: TokenStream) -> TokenStream { } } -/// #[derive(FromRow)] derives FromRow for struct -/// Works only on simple structs without generics etc +/// Documentation for this macro can only be found +/// in `scylla` crate - not in scylla-macros nor in scylla-cql. +/// This is because of rustdocs limitations that are hard to explain here. #[proc_macro_derive(FromRow, attributes(scylla_crate))] pub fn from_row_derive(tokens_input: TokenStream) -> TokenStream { let res = from_row::from_row_derive(tokens_input); res.unwrap_or_else(|e| e.into_compile_error().into()) } -/// #[derive(FromUserType)] allows to parse a struct as User Defined Type -/// Works only on simple structs without generics etc +/// Documentation for this macro can only be found +/// in `scylla` crate - not in scylla-macros nor in scylla-cql. +/// This is because of rustdocs limitations that are hard to explain here. #[proc_macro_derive(FromUserType, attributes(scylla_crate))] pub fn from_user_type_derive(tokens_input: TokenStream) -> TokenStream { let res = from_user_type::from_user_type_derive(tokens_input); res.unwrap_or_else(|e| e.into_compile_error().into()) } -/// #[derive(IntoUserType)] allows to parse a struct as User Defined Type -/// Works only on simple structs without generics etc +/// Documentation for this macro can only be found +/// in `scylla` crate - not in scylla-macros nor in scylla-cql. +/// This is because of rustdocs limitations that are hard to explain here. #[proc_macro_derive(IntoUserType, attributes(scylla_crate))] pub fn into_user_type_derive(tokens_input: TokenStream) -> TokenStream { let res = into_user_type::into_user_type_derive(tokens_input); res.unwrap_or_else(|e| e.into_compile_error().into()) } -/// #[derive(ValueList)] derives ValueList for struct -/// Works only on simple structs without generics etc +/// Documentation for this macro can only be found +/// in `scylla` crate - not in scylla-macros nor in scylla-cql. +/// This is because of rustdocs limitations that are hard to explain here. #[proc_macro_derive(ValueList, attributes(scylla_crate))] pub fn value_list_derive(tokens_input: TokenStream) -> TokenStream { let res = value_list::value_list_derive(tokens_input); From f6b9ee1f193d80873b642b9c1e40d0e0242ed6ad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Tue, 9 Jan 2024 02:44:32 +0100 Subject: [PATCH 3/7] Move derive macros docs to scylla crate --- scylla-cql/src/macros.rs | 216 --------------------------------------- scylla/src/lib.rs | 1 + scylla/src/macros.rs | 216 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 217 insertions(+), 216 deletions(-) diff --git a/scylla-cql/src/macros.rs b/scylla-cql/src/macros.rs index 92b89f2c02..0dd314cbdd 100644 --- a/scylla-cql/src/macros.rs +++ b/scylla-cql/src/macros.rs @@ -1,224 +1,8 @@ -/// #[derive(FromRow)] derives FromRow for struct -/// Works only on simple structs without generics etc pub use scylla_macros::FromRow; - -/// #[derive(FromUserType)] allows to parse struct as a User Defined Type -/// Works only on simple structs without generics etc pub use scylla_macros::FromUserType; - -/// #[derive(IntoUserType)] allows to pass struct a User Defined Type Value in queries -/// Works only on simple structs without generics etc pub use scylla_macros::IntoUserType; - -/// #[derive(ValueList)] allows to pass struct as a list of values for a query pub use scylla_macros::ValueList; - -/// Derive macro for the [`SerializeCql`](crate::types::serialize::value::SerializeCql) trait -/// which serializes given Rust structure as a User Defined Type (UDT). -/// -/// At the moment, only structs with named fields are supported. -/// -/// Serialization will fail if there are some fields in the Rust struct that don't match -/// to any of the UDT fields. -/// -/// If there are fields in UDT that are not present in Rust definition: -/// - serialization will succeed in "match_by_name" flavor (default). Missing -/// fields in the middle of UDT will be sent as NULLs, missing fields at the end will not be sent -/// at all. -/// - serialization will succed if suffix of UDT fields is missing. If there are missing fields in the -/// middle it will fail. Note that if "skip_name_checks" is enabled, and the types happen to match, -/// it is possible for serialization to succeed with unexpected result. -/// This behavior is the default to support ALTERing UDTs by adding new fields. -/// You can require exact match of fields using `force_exact_match` attribute. -/// -/// In case of failure, either [`BuiltinTypeCheckError`](crate::types::serialize::value::BuiltinTypeCheckError) -/// or [`BuiltinSerializationError`](crate::types::serialize::value::BuiltinSerializationError) -/// will be returned. -/// -/// # Example -/// -/// A UDT defined like this: -/// -/// ```notrust -/// CREATE TYPE ks.my_udt (a int, b text, c blob); -/// ``` -/// -/// ...can be serialized using the following struct: -/// -/// ```rust -/// # use scylla_cql::macros::SerializeCql; -/// #[derive(SerializeCql)] -/// # #[scylla(crate = scylla_cql)] -/// struct MyUdt { -/// a: i32, -/// b: Option, -/// // No "c" field - it is not mandatory by default for all fields to be present -/// } -/// ``` -/// -/// # Struct attributes -/// -/// `#[scylla(flavor = "flavor_name")]` -/// -/// Allows to choose one of the possible "flavors", i.e. the way how the -/// generated code will approach serialization. Possible flavors are: -/// -/// - `"match_by_name"` (default) - the generated implementation _does not -/// require_ the fields in the Rust struct to be in the same order as the -/// fields in the UDT. During serialization, the implementation will take -/// care to serialize the fields in the order which the database expects. -/// - `"enforce_order"` - the generated implementation _requires_ the fields -/// in the Rust struct to be in the same order as the fields in the UDT. -/// If the order is incorrect, type checking/serialization will fail. -/// This is a less robust flavor than `"match_by_name"`, but should be -/// slightly more performant as it doesn't need to perform lookups by name. -/// -/// `#[scylla(crate = crate_name)]` -/// -/// By default, the code generated by the derive macro will refer to the items -/// defined by the driver (types, traits, etc.) via the `::scylla` path. -/// For example, it will refer to the [`SerializeCql`](crate::types::serialize::value::SerializeCql) trait -/// using the following path: -/// -/// ```rust,ignore -/// use ::scylla::_macro_internal::SerializeCql; -/// ``` -/// -/// Most users will simply add `scylla` to their dependencies, then use -/// the derive macro and the path above will work. However, there are some -/// niche cases where this path will _not_ work: -/// -/// - The `scylla` crate is imported under a different name, -/// - The `scylla` crate is _not imported at all_ - the macro actually -/// is defined in the `scylla-macros` crate and the generated code depends -/// on items defined in `scylla-cql`. -/// -/// It's not possible to automatically resolve those issues in the procedural -/// macro itself, so in those cases the user must provide an alternative path -/// to either the `scylla` or `scylla-cql` crate. -/// -/// `#[scylla(skip_name_checks)]` -/// -/// _Specific only to the `enforce_order` flavor._ -/// -/// Skips checking Rust field names against names of the UDT fields. With this -/// annotation, the generated implementation will allow mismatch between Rust -/// struct field names and UDT field names, i.e. it's OK if i-th field has a -/// different name in Rust and in the UDT. Fields are still being type-checked. -/// -/// `#[scylla(force_exact_match)]` -/// -/// Forces Rust struct to have all the fields present in UDT, otherwise -/// serialization fails. -/// -/// # Field attributes -/// -/// `#[scylla(rename = "name_in_the_udt")]` -/// -/// Serializes the field to the UDT struct field with given name instead of -/// its Rust name. -/// -/// `#[scylla(skip)]` -/// -/// Don't use the field during serialization. pub use scylla_macros::SerializeCql; - -/// Derive macro for the [`SerializeRow`](crate::types::serialize::row::SerializeRow) trait -/// which serializes given Rust structure into bind markers for a CQL statement. -/// -/// At the moment, only structs with named fields are supported. -/// -/// Serialization will fail if there are some bind markers/columns in the statement -/// that don't match to any of the Rust struct fields, _or vice versa_. -/// -/// In case of failure, either [`BuiltinTypeCheckError`](crate::types::serialize::row::BuiltinTypeCheckError) -/// or [`BuiltinSerializationError`](crate::types::serialize::row::BuiltinSerializationError) -/// will be returned. -/// -/// # Example -/// -/// A UDT defined like this: -/// Given a table and a query: -/// -/// ```notrust -/// CREATE TABLE ks.my_t (a int PRIMARY KEY, b text, c blob); -/// INSERT INTO ks.my_t (a, b, c) VALUES (?, ?, ?); -/// ``` -/// -/// ...the values for the query can be serialized using the following struct: -/// -/// ```rust -/// # use scylla_cql::macros::SerializeRow; -/// #[derive(SerializeRow)] -/// # #[scylla(crate = scylla_cql)] -/// struct MyValues { -/// a: i32, -/// b: Option, -/// c: Vec, -/// } -/// ``` -/// -/// # Struct attributes -/// -/// `#[scylla(flavor = "flavor_name")]` -/// -/// Allows to choose one of the possible "flavors", i.e. the way how the -/// generated code will approach serialization. Possible flavors are: -/// -/// - `"match_by_name"` (default) - the generated implementation _does not -/// require_ the fields in the Rust struct to be in the same order as the -/// columns/bind markers. During serialization, the implementation will take -/// care to serialize the fields in the order which the database expects. -/// - `"enforce_order"` - the generated implementation _requires_ the fields -/// in the Rust struct to be in the same order as the columns/bind markers. -/// If the order is incorrect, type checking/serialization will fail. -/// This is a less robust flavor than `"match_by_name"`, but should be -/// slightly more performant as it doesn't need to perform lookups by name. -/// -/// `#[scylla(crate = crate_name)]` -/// -/// By default, the code generated by the derive macro will refer to the items -/// defined by the driver (types, traits, etc.) via the `::scylla` path. -/// For example, it will refer to the [`SerializeRow`](crate::types::serialize::row::SerializeRow) trait -/// using the following path: -/// -/// ```rust,ignore -/// use ::scylla::_macro_internal::SerializeRow; -/// ``` -/// -/// Most users will simply add `scylla` to their dependencies, then use -/// the derive macro and the path above will work. However, there are some -/// niche cases where this path will _not_ work: -/// -/// - The `scylla` crate is imported under a different name, -/// - The `scylla` crate is _not imported at all_ - the macro actually -/// is defined in the `scylla-macros` crate and the generated code depends -/// on items defined in `scylla-cql`. -/// -/// It's not possible to automatically resolve those issues in the procedural -/// macro itself, so in those cases the user must provide an alternative path -/// to either the `scylla` or `scylla-cql` crate. -/// -/// `#[scylla(skip_name_checks)] -/// -/// _Specific only to the `enforce_order` flavor._ -/// -/// Skips checking Rust field names against names of the columns / bind markers. -/// With this annotation, the generated implementation will allow mismatch -/// between Rust struct field names and the column / bind markers, i.e. it's -/// OK if i-th Rust struct field has a different name than the column / bind -/// marker. The values are still being type-checked. -/// -/// # Field attributes -/// -/// `#[scylla(rename = "column_or_bind_marker_name")]` -/// -/// Serializes the field to the column / bind marker with given name instead of -/// its Rust name. -/// -/// `#[scylla(skip)]` -/// -/// Don't use the field during serialization. pub use scylla_macros::SerializeRow; // Reexports for derive(IntoUserType) diff --git a/scylla/src/lib.rs b/scylla/src/lib.rs index 11198c1c95..381fad34d3 100644 --- a/scylla/src/lib.rs +++ b/scylla/src/lib.rs @@ -99,6 +99,7 @@ pub mod _macro_internal { } pub mod macros; +#[doc(inline)] pub use macros::*; pub use scylla_cql::frame; diff --git a/scylla/src/macros.rs b/scylla/src/macros.rs index 00bc9bfef5..959ab3f235 100644 --- a/scylla/src/macros.rs +++ b/scylla/src/macros.rs @@ -1,8 +1,224 @@ +/// #[derive(FromRow)] derives FromRow for struct +/// Works only on simple structs without generics etc pub use scylla_cql::macros::FromRow; + +/// #[derive(FromUserType)] allows to parse struct as a User Defined Type +/// Works only on simple structs without generics etc pub use scylla_cql::macros::FromUserType; + +/// #[derive(IntoUserType)] allows to pass struct a User Defined Type Value in queries +/// Works only on simple structs without generics etc pub use scylla_cql::macros::IntoUserType; + +/// Derive macro for the [`SerializeCql`](crate::types::serialize::value::SerializeCql) trait +/// which serializes given Rust structure as a User Defined Type (UDT). +/// +/// At the moment, only structs with named fields are supported. +/// +/// Serialization will fail if there are some fields in the Rust struct that don't match +/// to any of the UDT fields. +/// +/// If there are fields in UDT that are not present in Rust definition: +/// - serialization will succeed in "match_by_name" flavor (default). Missing +/// fields in the middle of UDT will be sent as NULLs, missing fields at the end will not be sent +/// at all. +/// - serialization will succed if suffix of UDT fields is missing. If there are missing fields in the +/// middle it will fail. Note that if "skip_name_checks" is enabled, and the types happen to match, +/// it is possible for serialization to succeed with unexpected result. +/// This behavior is the default to support ALTERing UDTs by adding new fields. +/// You can require exact match of fields using `force_exact_match` attribute. +/// +/// In case of failure, either [`BuiltinTypeCheckError`](crate::types::serialize::value::BuiltinTypeCheckError) +/// or [`BuiltinSerializationError`](crate::types::serialize::value::BuiltinSerializationError) +/// will be returned. +/// +/// # Example +/// +/// A UDT defined like this: +/// +/// ```notrust +/// CREATE TYPE ks.my_udt (a int, b text, c blob); +/// ``` +/// +/// ...can be serialized using the following struct: +/// +/// ```rust +/// # use scylla_cql::macros::SerializeCql; +/// #[derive(SerializeCql)] +/// # #[scylla(crate = scylla_cql)] +/// struct MyUdt { +/// a: i32, +/// b: Option, +/// // No "c" field - it is not mandatory by default for all fields to be present +/// } +/// ``` +/// +/// # Struct attributes +/// +/// `#[scylla(flavor = "flavor_name")]` +/// +/// Allows to choose one of the possible "flavors", i.e. the way how the +/// generated code will approach serialization. Possible flavors are: +/// +/// - `"match_by_name"` (default) - the generated implementation _does not +/// require_ the fields in the Rust struct to be in the same order as the +/// fields in the UDT. During serialization, the implementation will take +/// care to serialize the fields in the order which the database expects. +/// - `"enforce_order"` - the generated implementation _requires_ the fields +/// in the Rust struct to be in the same order as the fields in the UDT. +/// If the order is incorrect, type checking/serialization will fail. +/// This is a less robust flavor than `"match_by_name"`, but should be +/// slightly more performant as it doesn't need to perform lookups by name. +/// +/// `#[scylla(crate = crate_name)]` +/// +/// By default, the code generated by the derive macro will refer to the items +/// defined by the driver (types, traits, etc.) via the `::scylla` path. +/// For example, it will refer to the [`SerializeCql`](crate::types::serialize::value::SerializeCql) trait +/// using the following path: +/// +/// ```rust,ignore +/// use ::scylla::_macro_internal::SerializeCql; +/// ``` +/// +/// Most users will simply add `scylla` to their dependencies, then use +/// the derive macro and the path above will work. However, there are some +/// niche cases where this path will _not_ work: +/// +/// - The `scylla` crate is imported under a different name, +/// - The `scylla` crate is _not imported at all_ - the macro actually +/// is defined in the `scylla-macros` crate and the generated code depends +/// on items defined in `scylla-cql`. +/// +/// It's not possible to automatically resolve those issues in the procedural +/// macro itself, so in those cases the user must provide an alternative path +/// to either the `scylla` or `scylla-cql` crate. +/// +/// `#[scylla(skip_name_checks)]` +/// +/// _Specific only to the `enforce_order` flavor._ +/// +/// Skips checking Rust field names against names of the UDT fields. With this +/// annotation, the generated implementation will allow mismatch between Rust +/// struct field names and UDT field names, i.e. it's OK if i-th field has a +/// different name in Rust and in the UDT. Fields are still being type-checked. +/// +/// `#[scylla(force_exact_match)]` +/// +/// Forces Rust struct to have all the fields present in UDT, otherwise +/// serialization fails. +/// +/// # Field attributes +/// +/// `#[scylla(rename = "name_in_the_udt")]` +/// +/// Serializes the field to the UDT struct field with given name instead of +/// its Rust name. +/// +/// `#[scylla(skip)]` +/// +/// Don't use the field during serialization. pub use scylla_cql::macros::SerializeCql; + +/// Derive macro for the [`SerializeRow`](crate::types::serialize::row::SerializeRow) trait +/// which serializes given Rust structure into bind markers for a CQL statement. +/// +/// At the moment, only structs with named fields are supported. +/// +/// Serialization will fail if there are some bind markers/columns in the statement +/// that don't match to any of the Rust struct fields, _or vice versa_. +/// +/// In case of failure, either [`BuiltinTypeCheckError`](crate::types::serialize::row::BuiltinTypeCheckError) +/// or [`BuiltinSerializationError`](crate::types::serialize::row::BuiltinSerializationError) +/// will be returned. +/// +/// # Example +/// +/// A UDT defined like this: +/// Given a table and a query: +/// +/// ```notrust +/// CREATE TABLE ks.my_t (a int PRIMARY KEY, b text, c blob); +/// INSERT INTO ks.my_t (a, b, c) VALUES (?, ?, ?); +/// ``` +/// +/// ...the values for the query can be serialized using the following struct: +/// +/// ```rust +/// # use scylla_cql::macros::SerializeRow; +/// #[derive(SerializeRow)] +/// # #[scylla(crate = scylla_cql)] +/// struct MyValues { +/// a: i32, +/// b: Option, +/// c: Vec, +/// } +/// ``` +/// +/// # Struct attributes +/// +/// `#[scylla(flavor = "flavor_name")]` +/// +/// Allows to choose one of the possible "flavors", i.e. the way how the +/// generated code will approach serialization. Possible flavors are: +/// +/// - `"match_by_name"` (default) - the generated implementation _does not +/// require_ the fields in the Rust struct to be in the same order as the +/// columns/bind markers. During serialization, the implementation will take +/// care to serialize the fields in the order which the database expects. +/// - `"enforce_order"` - the generated implementation _requires_ the fields +/// in the Rust struct to be in the same order as the columns/bind markers. +/// If the order is incorrect, type checking/serialization will fail. +/// This is a less robust flavor than `"match_by_name"`, but should be +/// slightly more performant as it doesn't need to perform lookups by name. +/// +/// `#[scylla(crate = crate_name)]` +/// +/// By default, the code generated by the derive macro will refer to the items +/// defined by the driver (types, traits, etc.) via the `::scylla` path. +/// For example, it will refer to the [`SerializeRow`](crate::types::serialize::row::SerializeRow) trait +/// using the following path: +/// +/// ```rust,ignore +/// use ::scylla::_macro_internal::SerializeRow; +/// ``` +/// +/// Most users will simply add `scylla` to their dependencies, then use +/// the derive macro and the path above will work. However, there are some +/// niche cases where this path will _not_ work: +/// +/// - The `scylla` crate is imported under a different name, +/// - The `scylla` crate is _not imported at all_ - the macro actually +/// is defined in the `scylla-macros` crate and the generated code depends +/// on items defined in `scylla-cql`. +/// +/// It's not possible to automatically resolve those issues in the procedural +/// macro itself, so in those cases the user must provide an alternative path +/// to either the `scylla` or `scylla-cql` crate. +/// +/// `#[scylla(skip_name_checks)] +/// +/// _Specific only to the `enforce_order` flavor._ +/// +/// Skips checking Rust field names against names of the columns / bind markers. +/// With this annotation, the generated implementation will allow mismatch +/// between Rust struct field names and the column / bind markers, i.e. it's +/// OK if i-th Rust struct field has a different name than the column / bind +/// marker. The values are still being type-checked. +/// +/// # Field attributes +/// +/// `#[scylla(rename = "column_or_bind_marker_name")]` +/// +/// Serializes the field to the column / bind marker with given name instead of +/// its Rust name. +/// +/// `#[scylla(skip)]` +/// +/// Don't use the field during serialization. pub use scylla_cql::macros::SerializeRow; + +/// #[derive(ValueList)] allows to pass struct as a list of values for a query pub use scylla_cql::macros::ValueList; pub use scylla_cql::macros::impl_from_cql_value_from_method; From 64470f79c86b27e34ebb4e4e375dab678d4630e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Tue, 9 Jan 2024 02:49:13 +0100 Subject: [PATCH 4/7] scylla-cql: Inline `macros` module This module is now so small it doesn't make much sens to keep it in separate file. --- scylla-cql/src/lib.rs | 14 +++++++++++++- scylla-cql/src/macros.rs | 11 ----------- 2 files changed, 13 insertions(+), 12 deletions(-) delete mode 100644 scylla-cql/src/macros.rs diff --git a/scylla-cql/src/lib.rs b/scylla-cql/src/lib.rs index 83b6f3751e..95794184db 100644 --- a/scylla-cql/src/lib.rs +++ b/scylla-cql/src/lib.rs @@ -1,7 +1,19 @@ pub mod errors; pub mod frame; #[macro_use] -pub mod macros; +pub mod macros { + pub use scylla_macros::FromRow; + pub use scylla_macros::FromUserType; + pub use scylla_macros::IntoUserType; + pub use scylla_macros::SerializeCql; + pub use scylla_macros::SerializeRow; + pub use scylla_macros::ValueList; + + // Reexports for derive(IntoUserType) + pub use bytes::{BufMut, Bytes, BytesMut}; + + pub use crate::impl_from_cql_value_from_method; +} pub mod types; diff --git a/scylla-cql/src/macros.rs b/scylla-cql/src/macros.rs deleted file mode 100644 index 0dd314cbdd..0000000000 --- a/scylla-cql/src/macros.rs +++ /dev/null @@ -1,11 +0,0 @@ -pub use scylla_macros::FromRow; -pub use scylla_macros::FromUserType; -pub use scylla_macros::IntoUserType; -pub use scylla_macros::ValueList; -pub use scylla_macros::SerializeCql; -pub use scylla_macros::SerializeRow; - -// Reexports for derive(IntoUserType) -pub use bytes::{BufMut, Bytes, BytesMut}; - -pub use crate::impl_from_cql_value_from_method; From 5c7c12bac2d907ade96bbc2eb12dea5e1cead9d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Tue, 9 Jan 2024 13:57:04 +0100 Subject: [PATCH 5/7] Adjust macros docs to new paths Documentation was moved from scylla-cql to scylla, which made some paths used in those docs incorrect. This commit updates paths to correct ones. --- scylla/src/macros.rs | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/scylla/src/macros.rs b/scylla/src/macros.rs index 959ab3f235..453696239c 100644 --- a/scylla/src/macros.rs +++ b/scylla/src/macros.rs @@ -10,7 +10,7 @@ pub use scylla_cql::macros::FromUserType; /// Works only on simple structs without generics etc pub use scylla_cql::macros::IntoUserType; -/// Derive macro for the [`SerializeCql`](crate::types::serialize::value::SerializeCql) trait +/// Derive macro for the [`SerializeCql`](crate::serialize::value::SerializeCql) trait /// which serializes given Rust structure as a User Defined Type (UDT). /// /// At the moment, only structs with named fields are supported. @@ -28,8 +28,8 @@ pub use scylla_cql::macros::IntoUserType; /// This behavior is the default to support ALTERing UDTs by adding new fields. /// You can require exact match of fields using `force_exact_match` attribute. /// -/// In case of failure, either [`BuiltinTypeCheckError`](crate::types::serialize::value::BuiltinTypeCheckError) -/// or [`BuiltinSerializationError`](crate::types::serialize::value::BuiltinSerializationError) +/// In case of failure, either [`BuiltinTypeCheckError`](crate::serialize::value::BuiltinTypeCheckError) +/// or [`BuiltinSerializationError`](crate::serialize::value::BuiltinSerializationError) /// will be returned. /// /// # Example @@ -43,9 +43,8 @@ pub use scylla_cql::macros::IntoUserType; /// ...can be serialized using the following struct: /// /// ```rust -/// # use scylla_cql::macros::SerializeCql; +/// # use scylla::SerializeCql; /// #[derive(SerializeCql)] -/// # #[scylla(crate = scylla_cql)] /// struct MyUdt { /// a: i32, /// b: Option, @@ -74,7 +73,7 @@ pub use scylla_cql::macros::IntoUserType; /// /// By default, the code generated by the derive macro will refer to the items /// defined by the driver (types, traits, etc.) via the `::scylla` path. -/// For example, it will refer to the [`SerializeCql`](crate::types::serialize::value::SerializeCql) trait +/// For example, it will refer to the [`SerializeCql`](crate::serialize::value::SerializeCql) trait /// using the following path: /// /// ```rust,ignore @@ -120,7 +119,7 @@ pub use scylla_cql::macros::IntoUserType; /// Don't use the field during serialization. pub use scylla_cql::macros::SerializeCql; -/// Derive macro for the [`SerializeRow`](crate::types::serialize::row::SerializeRow) trait +/// Derive macro for the [`SerializeRow`](crate::serialize::row::SerializeRow) trait /// which serializes given Rust structure into bind markers for a CQL statement. /// /// At the moment, only structs with named fields are supported. @@ -128,8 +127,8 @@ pub use scylla_cql::macros::SerializeCql; /// Serialization will fail if there are some bind markers/columns in the statement /// that don't match to any of the Rust struct fields, _or vice versa_. /// -/// In case of failure, either [`BuiltinTypeCheckError`](crate::types::serialize::row::BuiltinTypeCheckError) -/// or [`BuiltinSerializationError`](crate::types::serialize::row::BuiltinSerializationError) +/// In case of failure, either [`BuiltinTypeCheckError`](crate::serialize::row::BuiltinTypeCheckError) +/// or [`BuiltinSerializationError`](crate::serialize::row::BuiltinSerializationError) /// will be returned. /// /// # Example @@ -145,9 +144,8 @@ pub use scylla_cql::macros::SerializeCql; /// ...the values for the query can be serialized using the following struct: /// /// ```rust -/// # use scylla_cql::macros::SerializeRow; +/// # use scylla::SerializeRow; /// #[derive(SerializeRow)] -/// # #[scylla(crate = scylla_cql)] /// struct MyValues { /// a: i32, /// b: Option, @@ -176,7 +174,7 @@ pub use scylla_cql::macros::SerializeCql; /// /// By default, the code generated by the derive macro will refer to the items /// defined by the driver (types, traits, etc.) via the `::scylla` path. -/// For example, it will refer to the [`SerializeRow`](crate::types::serialize::row::SerializeRow) trait +/// For example, it will refer to the [`SerializeRow`](crate::serialize::row::SerializeRow) trait /// using the following path: /// /// ```rust,ignore From 32411d3ca795e426f22953bbfb6ffb7fc108c49e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 12 Jan 2024 12:35:18 +0100 Subject: [PATCH 6/7] scylla: Add separators in derive macros docs Rustdocs merges documentation of re-exports with documentation of original item. Because of this there is a need for separator, so that stubs from scylla-macros crate are not mixed up with docs present in scylla crate. --- scylla/src/macros.rs | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/scylla/src/macros.rs b/scylla/src/macros.rs index 453696239c..62e2618d60 100644 --- a/scylla/src/macros.rs +++ b/scylla/src/macros.rs @@ -1,13 +1,22 @@ /// #[derive(FromRow)] derives FromRow for struct /// Works only on simple structs without generics etc +/// +/// --- +/// pub use scylla_cql::macros::FromRow; /// #[derive(FromUserType)] allows to parse struct as a User Defined Type /// Works only on simple structs without generics etc +/// +/// --- +/// pub use scylla_cql::macros::FromUserType; /// #[derive(IntoUserType)] allows to pass struct a User Defined Type Value in queries /// Works only on simple structs without generics etc +/// +/// --- +/// pub use scylla_cql::macros::IntoUserType; /// Derive macro for the [`SerializeCql`](crate::serialize::value::SerializeCql) trait @@ -117,6 +126,9 @@ pub use scylla_cql::macros::IntoUserType; /// `#[scylla(skip)]` /// /// Don't use the field during serialization. +/// +/// --- +/// pub use scylla_cql::macros::SerializeCql; /// Derive macro for the [`SerializeRow`](crate::serialize::row::SerializeRow) trait @@ -214,9 +226,15 @@ pub use scylla_cql::macros::SerializeCql; /// `#[scylla(skip)]` /// /// Don't use the field during serialization. +/// +/// --- +/// pub use scylla_cql::macros::SerializeRow; /// #[derive(ValueList)] allows to pass struct as a list of values for a query +/// +/// --- +/// pub use scylla_cql::macros::ValueList; pub use scylla_cql::macros::impl_from_cql_value_from_method; From 7933112f2961914d60dcdb3cc6ec53994095e672 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=20Bary=C5=82a?= Date: Fri, 12 Jan 2024 12:38:27 +0100 Subject: [PATCH 7/7] scylla: Add empty lines in old derive macros docs Without those lines, whole doc for an item is merged and shown in the summary, which makes it hard to read. --- scylla/src/macros.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/scylla/src/macros.rs b/scylla/src/macros.rs index 62e2618d60..67a7461bf7 100644 --- a/scylla/src/macros.rs +++ b/scylla/src/macros.rs @@ -1,4 +1,5 @@ /// #[derive(FromRow)] derives FromRow for struct +/// /// Works only on simple structs without generics etc /// /// --- @@ -6,6 +7,7 @@ pub use scylla_cql::macros::FromRow; /// #[derive(FromUserType)] allows to parse struct as a User Defined Type +/// /// Works only on simple structs without generics etc /// /// --- @@ -13,6 +15,7 @@ pub use scylla_cql::macros::FromRow; pub use scylla_cql::macros::FromUserType; /// #[derive(IntoUserType)] allows to pass struct a User Defined Type Value in queries +/// /// Works only on simple structs without generics etc /// /// ---