Merge pull request #907 from Lorak-mmk/workaround_macros_docs

Move derive macros docs to scylla crate

Author: piodul

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;
 

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);

scylla/src/lib.rs

@@ -98,8 +98,11 @@ pub mod _macro_internal {
     pub use scylla_cql::_macro_internal::*;
 }
 
+pub mod macros;
+#[doc(inline)]
+pub use macros::*;
+
 pub use scylla_cql::frame;
-pub use scylla_cql::macros::{self, *};
 pub use scylla_cql::types::serialize;
 
 pub mod authentication;

scylla-cql/src/macros.rs scylla/src/macros.rs

@@ -1,19 +1,28 @@
 /// #[derive(FromRow)] derives FromRow for struct
+///
 /// Works only on simple structs without generics etc
-pub use scylla_macros::FromRow;
+///
+/// ---
+///
+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_macros::FromUserType;
+///
+/// ---
+///
+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_macros::IntoUserType;
-
-/// #[derive(ValueList)] allows to pass struct as a list of values for a query
-pub use scylla_macros::ValueList;
+///
+/// ---
+///
+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.
@@ -31,8 +40,8 @@ pub use scylla_macros::ValueList;
 /// 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
@@ -46,9 +55,8 @@ pub use scylla_macros::ValueList;
 /// ...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<String>,
@@ -77,7 +85,7 @@ pub use scylla_macros::ValueList;
 ///
 /// 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
@@ -121,18 +129,21 @@ pub use scylla_macros::ValueList;
 /// `#[scylla(skip)]`
 ///
 /// Don't use the field during serialization.
-pub use scylla_macros::SerializeCql;
+///
+/// ---
+///
+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.
 ///
 /// 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
@@ -148,9 +159,8 @@ pub use scylla_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<String>,
@@ -179,7 +189,7 @@ pub use scylla_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
@@ -219,9 +229,18 @@ pub use scylla_macros::SerializeCql;
 /// `#[scylla(skip)]`
 ///
 /// Don't use the field during serialization.
-pub use scylla_macros::SerializeRow;
+///
+/// ---
+///
+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;
 
 // Reexports for derive(IntoUserType)
 pub use bytes::{BufMut, Bytes, BytesMut};
-
-pub use crate::impl_from_cql_value_from_method;