Skip to content

Commit f6b9ee1

Browse files
Lorak-mmkLorak-mmk
committed
Move derive macros docs to scylla crate
1 parent 4c154ba commit f6b9ee1

File tree

3 files changed

+217
-216
lines changed

3 files changed

+217
-216
lines changed

‎scylla-cql/src/macros.rs‎

Lines changed: 0 additions & 216 deletions
Original file line numberDiff line numberDiff line change
@@ -1,224 +1,8 @@
1-
/// #[derive(FromRow)] derives FromRow for struct
2-
/// Works only on simple structs without generics etc
31
pub use scylla_macros::FromRow;
4-
5-
/// #[derive(FromUserType)] allows to parse struct as a User Defined Type
6-
/// Works only on simple structs without generics etc
72
pub use scylla_macros::FromUserType;
8-
9-
/// #[derive(IntoUserType)] allows to pass struct a User Defined Type Value in queries
10-
/// Works only on simple structs without generics etc
113
pub use scylla_macros::IntoUserType;
12-
13-
/// #[derive(ValueList)] allows to pass struct as a list of values for a query
144
pub use scylla_macros::ValueList;
15-
16-
/// Derive macro for the [`SerializeCql`](crate::types::serialize::value::SerializeCql) trait
17-
/// which serializes given Rust structure as a User Defined Type (UDT).
18-
///
19-
/// At the moment, only structs with named fields are supported.
20-
///
21-
/// Serialization will fail if there are some fields in the Rust struct that don't match
22-
/// to any of the UDT fields.
23-
///
24-
/// If there are fields in UDT that are not present in Rust definition:
25-
/// - serialization will succeed in "match_by_name" flavor (default). Missing
26-
/// fields in the middle of UDT will be sent as NULLs, missing fields at the end will not be sent
27-
/// at all.
28-
/// - serialization will succed if suffix of UDT fields is missing. If there are missing fields in the
29-
/// middle it will fail. Note that if "skip_name_checks" is enabled, and the types happen to match,
30-
/// it is possible for serialization to succeed with unexpected result.
31-
/// This behavior is the default to support ALTERing UDTs by adding new fields.
32-
/// You can require exact match of fields using `force_exact_match` attribute.
33-
///
34-
/// In case of failure, either [`BuiltinTypeCheckError`](crate::types::serialize::value::BuiltinTypeCheckError)
35-
/// or [`BuiltinSerializationError`](crate::types::serialize::value::BuiltinSerializationError)
36-
/// will be returned.
37-
///
38-
/// # Example
39-
///
40-
/// A UDT defined like this:
41-
///
42-
/// ```notrust
43-
/// CREATE TYPE ks.my_udt (a int, b text, c blob);
44-
/// ```
45-
///
46-
/// ...can be serialized using the following struct:
47-
///
48-
/// ```rust
49-
/// # use scylla_cql::macros::SerializeCql;
50-
/// #[derive(SerializeCql)]
51-
/// # #[scylla(crate = scylla_cql)]
52-
/// struct MyUdt {
53-
/// a: i32,
54-
/// b: Option<String>,
55-
/// // No "c" field - it is not mandatory by default for all fields to be present
56-
/// }
57-
/// ```
58-
///
59-
/// # Struct attributes
60-
///
61-
/// `#[scylla(flavor = "flavor_name")]`
62-
///
63-
/// Allows to choose one of the possible "flavors", i.e. the way how the
64-
/// generated code will approach serialization. Possible flavors are:
65-
///
66-
/// - `"match_by_name"` (default) - the generated implementation _does not
67-
/// require_ the fields in the Rust struct to be in the same order as the
68-
/// fields in the UDT. During serialization, the implementation will take
69-
/// care to serialize the fields in the order which the database expects.
70-
/// - `"enforce_order"` - the generated implementation _requires_ the fields
71-
/// in the Rust struct to be in the same order as the fields in the UDT.
72-
/// If the order is incorrect, type checking/serialization will fail.
73-
/// This is a less robust flavor than `"match_by_name"`, but should be
74-
/// slightly more performant as it doesn't need to perform lookups by name.
75-
///
76-
/// `#[scylla(crate = crate_name)]`
77-
///
78-
/// By default, the code generated by the derive macro will refer to the items
79-
/// defined by the driver (types, traits, etc.) via the `::scylla` path.
80-
/// For example, it will refer to the [`SerializeCql`](crate::types::serialize::value::SerializeCql) trait
81-
/// using the following path:
82-
///
83-
/// ```rust,ignore
84-
/// use ::scylla::_macro_internal::SerializeCql;
85-
/// ```
86-
///
87-
/// Most users will simply add `scylla` to their dependencies, then use
88-
/// the derive macro and the path above will work. However, there are some
89-
/// niche cases where this path will _not_ work:
90-
///
91-
/// - The `scylla` crate is imported under a different name,
92-
/// - The `scylla` crate is _not imported at all_ - the macro actually
93-
/// is defined in the `scylla-macros` crate and the generated code depends
94-
/// on items defined in `scylla-cql`.
95-
///
96-
/// It's not possible to automatically resolve those issues in the procedural
97-
/// macro itself, so in those cases the user must provide an alternative path
98-
/// to either the `scylla` or `scylla-cql` crate.
99-
///
100-
/// `#[scylla(skip_name_checks)]`
101-
///
102-
/// _Specific only to the `enforce_order` flavor._
103-
///
104-
/// Skips checking Rust field names against names of the UDT fields. With this
105-
/// annotation, the generated implementation will allow mismatch between Rust
106-
/// struct field names and UDT field names, i.e. it's OK if i-th field has a
107-
/// different name in Rust and in the UDT. Fields are still being type-checked.
108-
///
109-
/// `#[scylla(force_exact_match)]`
110-
///
111-
/// Forces Rust struct to have all the fields present in UDT, otherwise
112-
/// serialization fails.
113-
///
114-
/// # Field attributes
115-
///
116-
/// `#[scylla(rename = "name_in_the_udt")]`
117-
///
118-
/// Serializes the field to the UDT struct field with given name instead of
119-
/// its Rust name.
120-
///
121-
/// `#[scylla(skip)]`
122-
///
123-
/// Don't use the field during serialization.
1245
pub use scylla_macros::SerializeCql;
125-
126-
/// Derive macro for the [`SerializeRow`](crate::types::serialize::row::SerializeRow) trait
127-
/// which serializes given Rust structure into bind markers for a CQL statement.
128-
///
129-
/// At the moment, only structs with named fields are supported.
130-
///
131-
/// Serialization will fail if there are some bind markers/columns in the statement
132-
/// that don't match to any of the Rust struct fields, _or vice versa_.
133-
///
134-
/// In case of failure, either [`BuiltinTypeCheckError`](crate::types::serialize::row::BuiltinTypeCheckError)
135-
/// or [`BuiltinSerializationError`](crate::types::serialize::row::BuiltinSerializationError)
136-
/// will be returned.
137-
///
138-
/// # Example
139-
///
140-
/// A UDT defined like this:
141-
/// Given a table and a query:
142-
///
143-
/// ```notrust
144-
/// CREATE TABLE ks.my_t (a int PRIMARY KEY, b text, c blob);
145-
/// INSERT INTO ks.my_t (a, b, c) VALUES (?, ?, ?);
146-
/// ```
147-
///
148-
/// ...the values for the query can be serialized using the following struct:
149-
///
150-
/// ```rust
151-
/// # use scylla_cql::macros::SerializeRow;
152-
/// #[derive(SerializeRow)]
153-
/// # #[scylla(crate = scylla_cql)]
154-
/// struct MyValues {
155-
/// a: i32,
156-
/// b: Option<String>,
157-
/// c: Vec<u8>,
158-
/// }
159-
/// ```
160-
///
161-
/// # Struct attributes
162-
///
163-
/// `#[scylla(flavor = "flavor_name")]`
164-
///
165-
/// Allows to choose one of the possible "flavors", i.e. the way how the
166-
/// generated code will approach serialization. Possible flavors are:
167-
///
168-
/// - `"match_by_name"` (default) - the generated implementation _does not
169-
/// require_ the fields in the Rust struct to be in the same order as the
170-
/// columns/bind markers. During serialization, the implementation will take
171-
/// care to serialize the fields in the order which the database expects.
172-
/// - `"enforce_order"` - the generated implementation _requires_ the fields
173-
/// in the Rust struct to be in the same order as the columns/bind markers.
174-
/// If the order is incorrect, type checking/serialization will fail.
175-
/// This is a less robust flavor than `"match_by_name"`, but should be
176-
/// slightly more performant as it doesn't need to perform lookups by name.
177-
///
178-
/// `#[scylla(crate = crate_name)]`
179-
///
180-
/// By default, the code generated by the derive macro will refer to the items
181-
/// defined by the driver (types, traits, etc.) via the `::scylla` path.
182-
/// For example, it will refer to the [`SerializeRow`](crate::types::serialize::row::SerializeRow) trait
183-
/// using the following path:
184-
///
185-
/// ```rust,ignore
186-
/// use ::scylla::_macro_internal::SerializeRow;
187-
/// ```
188-
///
189-
/// Most users will simply add `scylla` to their dependencies, then use
190-
/// the derive macro and the path above will work. However, there are some
191-
/// niche cases where this path will _not_ work:
192-
///
193-
/// - The `scylla` crate is imported under a different name,
194-
/// - The `scylla` crate is _not imported at all_ - the macro actually
195-
/// is defined in the `scylla-macros` crate and the generated code depends
196-
/// on items defined in `scylla-cql`.
197-
///
198-
/// It's not possible to automatically resolve those issues in the procedural
199-
/// macro itself, so in those cases the user must provide an alternative path
200-
/// to either the `scylla` or `scylla-cql` crate.
201-
///
202-
/// `#[scylla(skip_name_checks)]
203-
///
204-
/// _Specific only to the `enforce_order` flavor._
205-
///
206-
/// Skips checking Rust field names against names of the columns / bind markers.
207-
/// With this annotation, the generated implementation will allow mismatch
208-
/// between Rust struct field names and the column / bind markers, i.e. it's
209-
/// OK if i-th Rust struct field has a different name than the column / bind
210-
/// marker. The values are still being type-checked.
211-
///
212-
/// # Field attributes
213-
///
214-
/// `#[scylla(rename = "column_or_bind_marker_name")]`
215-
///
216-
/// Serializes the field to the column / bind marker with given name instead of
217-
/// its Rust name.
218-
///
219-
/// `#[scylla(skip)]`
220-
///
221-
/// Don't use the field during serialization.
2226
pub use scylla_macros::SerializeRow;
2237

2248
// Reexports for derive(IntoUserType)

‎scylla/src/lib.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,7 @@ pub mod _macro_internal {
9999
}
100100

101101
pub mod macros;
102+
#[doc(inline)]
102103
pub use macros::*;
103104

104105
pub use scylla_cql::frame;

0 commit comments

Comments
 (0)