doc: document #[derive(Row)]

Author: abonander

derive/src/lib.rs

@@ -12,6 +12,16 @@ mod attributes;
 #[cfg(test)]
 mod tests;
 
+// TODO: support wrappers `Wrapper(Inner)` and `Wrapper<T>(T)`.
+// TODO: support the `nested` attribute.
+#[proc_macro_derive(Row, attributes(clickhouse))]
+pub fn row(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
+    let input = parse_macro_input!(input as DeriveInput);
+    row_impl(input)
+        .unwrap_or_else(Error::into_compile_error)
+        .into()
+}
+
 fn column_names(data: &DataStruct, cx: &Ctxt, container: &Container) -> Result<TokenStream> {
     Ok(match &data.fields {
         Fields::Named(fields) => {
@@ -39,16 +49,6 @@ fn column_names(data: &DataStruct, cx: &Ctxt, container: &Container) -> Result<T
     })
 }
 
-// TODO: support wrappers `Wrapper(Inner)` and `Wrapper<T>(T)`.
-// TODO: support the `nested` attribute.
-#[proc_macro_derive(Row, attributes(clickhouse))]
-pub fn row(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
-    let input = parse_macro_input!(input as DeriveInput);
-    row_impl(input)
-        .unwrap_or_else(Error::into_compile_error)
-        .into()
-}
-
 fn row_impl(input: DeriveInput) -> Result<TokenStream> {
     let cx = Ctxt::new();
 

src/lib.rs

@@ -10,7 +10,10 @@ pub use self::{
     row::{Row, RowOwned, RowRead, RowWrite},
 };
 use self::{error::Result, http_client::HttpClient};
+
+#[doc = include_str!("row_derive.md")]
 pub use clickhouse_derive::Row;
+
 use std::{collections::HashMap, fmt::Display, sync::Arc};
 
 pub mod error;

src/row.rs

@@ -13,15 +13,17 @@ pub enum RowKind {
 /// Represents a row that can be used in queries.
 ///
 /// Implemented for:
-/// * All `#[derive(Row)]` items
+/// * All [`#[derive(Row)]`][row-derive] items
 /// * `(P1, P2, ...)` where P* is a primitive type or string
 ///
-/// Do not implement this trait directly, use `#[derive(Row)]` instead.
+/// Do not implement this trait directly, use [`#[derive(Row)]`][row-derive] instead.
 ///
 /// In order to write a generic code over rows, check
 /// * [`RowRead`] for reading queries.
 /// * [`RowWrite`] for writing queries.
 /// * [`RowOwned`] for rows that do not hold any references.
+///
+/// [row-derive]: derive@crate::Row
 pub trait Row {
     // NOTE: all properties are unstable and, hence, not following semver.
 

src/row_derive.md

@@ -0,0 +1,41 @@
+Derive macro for [`Row`][trait@crate::Row].
+
+```rust,no_run
+use clickhouse::Row;
+
+#[derive(Row)]
+struct MyRow {
+    foo: u32,
+    bar: String,
+    baz: bool, 
+}
+```
+
+# `#[clickhouse(crate = "...")]`
+
+Override the name of the `clickhouse` crate where referenced by the macro.
+
+Useful if the `clickhouse` package is renamed in Cargo.
+
+
+## Example
+`Cargo.toml`:
+```toml
+# Renames the `clickhouse` dependency to `foo`
+[dependencies.foo]
+package = "clickhouse"
+version = "0.14"
+```
+
+```rust,no_run
+# extern crate clickhouse as foo;
+use foo::Row;
+
+#[derive(Row)]
+#[clickhouse(crate = "foo")]
+struct MyRow {
+    foo: u32,
+    bar: String,
+    baz: bool, 
+}
+```