Document the macros.

Add code examples for the macros

sea-orm-macros/src/attributes.rs

@@ -1,6 +1,7 @@
 pub mod derive_attr {
     use bae::FromAttributes;
 
+    /// Attributes for Models and ActiveModels
     #[derive(Default, FromAttributes)]
     pub struct SeaOrm {
         pub column: Option<syn::Ident>,
@@ -16,6 +17,7 @@ pub mod derive_attr {
 pub mod field_attr {
     use bae::FromAttributes;
 
+    /// Operations for Models and ActiveModels
     #[derive(Default, FromAttributes)]
     pub struct SeaOrm {
         pub belongs_to: Option<syn::Lit>,

sea-orm-macros/src/derives/active_model.rs

@@ -4,6 +4,7 @@ use proc_macro2::{Ident, TokenStream};
 use quote::{format_ident, quote, quote_spanned};
 use syn::{punctuated::Punctuated, token::Comma, Data, DataStruct, Field, Fields, Lit, Meta, Type};
 
+/// Method to derive an [ActiveModel](sea_orm::ActiveModel)
 pub fn expand_derive_active_model(ident: Ident, data: Data) -> syn::Result<TokenStream> {
     let fields = match data {
         Data::Struct(DataStruct {

sea-orm-macros/src/derives/active_model_behavior.rs

@@ -2,6 +2,7 @@ use proc_macro2::{Ident, TokenStream};
 use quote::quote;
 use syn::Data;
 
+/// Method to derive an implementation of [ActiveModelBehavior](sea_orm::ActiveModelBehavior)
 pub fn expand_derive_active_model_behavior(_ident: Ident, _data: Data) -> syn::Result<TokenStream> {
     Ok(quote!(
         #[automatically_derived]

sea-orm-macros/src/derives/column.rs

@@ -3,6 +3,8 @@ use proc_macro2::{Ident, TokenStream};
 use quote::{quote, quote_spanned};
 use syn::{punctuated::Punctuated, token::Comma, Data, DataEnum, Fields, Lit, Meta, Variant};
 
+/// FIXME
+/// Method to derive default column names from a &str
 pub fn impl_default_as_str(ident: &Ident, data: &Data) -> syn::Result<TokenStream> {
     let variants = match data {
         syn::Data::Enum(DataEnum { variants, .. }) => variants,
@@ -65,6 +67,7 @@ pub fn impl_default_as_str(ident: &Ident, data: &Data) -> syn::Result<TokenStrea
     ))
 }
 
+/// Implement a column using for an enum using [DeriveColumn](sea_orm::DeriveColumn)
 pub fn impl_col_from_str(ident: &Ident, data: &Data) -> syn::Result<TokenStream> {
     let data_enum = match data {
         Data::Enum(data_enum) => data_enum,
@@ -114,6 +117,7 @@ pub fn expand_derive_column(ident: &Ident, data: &Data) -> syn::Result<TokenStre
     ))
 }
 
+/// Derive a column with a non_snake_case name
 pub fn expand_derive_custom_column(ident: &Ident, data: &Data) -> syn::Result<TokenStream> {
     let impl_default_as_str = impl_default_as_str(ident, data)?;
     let impl_col_from_str = impl_col_from_str(ident, data)?;

sea-orm-macros/src/derives/entity_model.rs

@@ -7,6 +7,7 @@ use syn::{
     Lit, Meta,
 };
 
+/// Method to derive an Model
 pub fn expand_derive_entity_model(data: Data, attrs: Vec<Attribute>) -> syn::Result<TokenStream> {
     // if #[sea_orm(table_name = "foo", schema_name = "bar")] specified, create Entity struct
     let mut table_name = None;

sea-orm-macros/src/derives/from_query_result.rs

@@ -2,6 +2,7 @@ use proc_macro2::{Ident, TokenStream};
 use quote::{format_ident, quote, quote_spanned};
 use syn::{Data, DataStruct, Field, Fields};
 
+/// Method to derive a [QueryResult](sea_orm::QueryResult)
 pub fn expand_derive_from_query_result(ident: Ident, data: Data) -> syn::Result<TokenStream> {
     let fields = match data {
         Data::Struct(DataStruct {

sea-orm-macros/src/derives/into_active_model.rs

@@ -2,6 +2,7 @@ use bae::FromAttributes;
 use proc_macro2::{Span, TokenStream};
 use quote::{quote, quote_spanned};
 
+/// Attributes to derive an ActiveModel
 #[derive(Default, FromAttributes)]
 pub struct SeaOrm {
     pub active_model: Option<syn::Ident>,
@@ -89,6 +90,7 @@ impl IntoActiveModel {
     }
 }
 
+/// Method to derive the ActiveModel from the [ActiveModelTrait](sea_orm::ActiveModelTrait)
 pub fn expand_into_active_model(input: syn::DeriveInput) -> syn::Result<TokenStream> {
     let ident_span = input.ident.span();
 

sea-orm-macros/src/derives/model.rs

@@ -183,6 +183,7 @@ impl DeriveModel {
     }
 }
 
+/// Method to derive an ActiveModel
 pub fn expand_derive_model(input: syn::DeriveInput) -> syn::Result<TokenStream> {
     let ident_span = input.ident.span();
 

sea-orm-macros/src/derives/primary_key.rs

@@ -3,6 +3,7 @@ use proc_macro2::{Ident, TokenStream};
 use quote::{quote, quote_spanned};
 use syn::{Data, DataEnum, Fields, Variant};
 
+/// Method to derive a Primary Key for a Model using the [PrimaryKeyTrait](sea_orm::PrimaryKeyTrait)
 pub fn expand_derive_primary_key(ident: Ident, data: Data) -> syn::Result<TokenStream> {
     let variants = match data {
         syn::Data::Enum(DataEnum { variants, .. }) => variants,

sea-orm-macros/src/derives/relation.rs

@@ -166,6 +166,7 @@ impl DeriveRelation {
     }
 }
 
+/// Method to derive a Relation
 pub fn expand_derive_relation(input: syn::DeriveInput) -> syn::Result<TokenStream> {
     let ident_span = input.ident.span();
 

sea-orm-macros/src/lib.rs

@@ -7,6 +7,14 @@ mod attributes;
 mod derives;
 mod util;
 
+/// Create an Entity
+/// ### Usage
+/// ```
+/// use sea_orm::entity::prelude::*;
+///
+///#[derive(Copy, Clone, Default, Debug, DeriveEntity)]
+///pub struct Entity;
+/// ```
 #[proc_macro_derive(DeriveEntity, attributes(sea_orm))]
 pub fn derive_entity(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as DeriveInput);
@@ -15,6 +23,21 @@ pub fn derive_entity(input: TokenStream) -> TokenStream {
         .into()
 }
 
+/// This derive macro is the 'almighty' macro which automatically generates
+/// Entity, Column, and PrimaryKey from a given Model.
+/// ### Usage
+/// use sea_orm::entity::prelude::*;
+///
+/// #[derive(Clone, Debug, PartialEq, DeriveEntityModel, Deserialize, Serialize, FromForm)]
+/// #[sea_orm(table_name = "posts")]
+/// pub struct Model {
+///     #[sea_orm(primary_key)]
+///     pub id: i32,
+///     pub title: String,
+///     #[sea_orm(column_type = "Text")]
+///     pub text: String,
+/// }
+/// ```
 #[proc_macro_derive(DeriveEntityModel, attributes(sea_orm))]
 pub fn derive_entity_model(input: TokenStream) -> TokenStream {
     let input_ts = input.clone();
@@ -36,6 +59,19 @@ pub fn derive_entity_model(input: TokenStream) -> TokenStream {
     ts
 }
 
+/// The DerivePrimaryKey derive macro will implement [PrimaryKeyToColumn]
+/// for PrimaryKey which defines tedious mappings between primary keys and columns.
+/// The [EnumIter] is also derived, allowing iteration over all enum variants.
+/// ### Usage
+/// ```
+/// use sea_orm::entity::prelude::*;
+///
+/// #[derive(Copy, Clone, Debug, EnumIter, DerivePrimaryKey)]
+/// pub enum PrimaryKey {
+///     CakeId,
+///     FillingId,
+/// }
+/// ```
 #[proc_macro_derive(DerivePrimaryKey)]
 pub fn derive_primary_key(input: TokenStream) -> TokenStream {
     let DeriveInput { ident, data, .. } = parse_macro_input!(input);
@@ -46,6 +82,19 @@ pub fn derive_primary_key(input: TokenStream) -> TokenStream {
     }
 }
 
+/// The DeriveColumn derive macro will implement [ColumnTrait] for Columns.
+/// It defines the identifier of each column by implementing Iden and IdenStatic.
+/// The EnumIter is also derived, allowing iteration over all enum variants.
+/// ### Usage
+/// ```
+/// use sea_orm::entity::prelude::*;
+///
+/// #[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)]
+/// pub enum Column {
+///     CakeId,
+///     FillingId,
+/// }
+/// ```
 #[proc_macro_derive(DeriveColumn, attributes(sea_orm))]
 pub fn derive_column(input: TokenStream) -> TokenStream {
     let DeriveInput { ident, data, .. } = parse_macro_input!(input);
@@ -56,6 +105,13 @@ pub fn derive_column(input: TokenStream) -> TokenStream {
     }
 }
 
+/// Derive a column if column names are not in snake-case
+/// #[derive(Copy, Clone, Debug, EnumIter, DeriveCustomColumn)]
+/// pub enum Column {
+///     Id,
+///     Name,
+///     VendorId,
+/// }
 #[proc_macro_derive(DeriveCustomColumn)]
 pub fn derive_custom_column(input: TokenStream) -> TokenStream {
     let DeriveInput { ident, data, .. } = parse_macro_input!(input);
@@ -66,6 +122,18 @@ pub fn derive_custom_column(input: TokenStream) -> TokenStream {
     }
 }
 
+/// The DeriveModel derive macro will implement ModelTrait for Model,
+/// which provides setters and getters for all attributes in the mod
+/// It also implements FromQueryResult to convert a query result into the corresponding Model.
+/// ### Usage
+///
+/// ```
+/// #[derive(Clone, Debug, PartialEq, DeriveModel, DeriveActiveModel)]
+/// pub struct Model {
+///     pub id: i32,
+///     pub name: String,
+/// }
+/// ```
 #[proc_macro_derive(DeriveModel, attributes(sea_orm))]
 pub fn derive_model(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as DeriveInput);
@@ -74,6 +142,19 @@ pub fn derive_model(input: TokenStream) -> TokenStream {
         .into()
 }
 
+/// The DeriveActiveModel derive macro will implement ActiveModelTrait for ActiveModel
+/// which provides setters and getters for all active values in the active model.
+/// ### Usage
+///
+/// ```
+///
+/// #[derive(Clone, Debug, PartialEq, DeriveModel, DeriveActiveModel)]
+/// pub struct Model {
+///     pub id: i32,
+///     pub name: String,
+/// }
+///
+/// ```
 #[proc_macro_derive(DeriveActiveModel, attributes(sea_orm))]
 pub fn derive_active_model(input: TokenStream) -> TokenStream {
     let DeriveInput { ident, data, .. } = parse_macro_input!(input);
@@ -84,6 +165,7 @@ pub fn derive_active_model(input: TokenStream) -> TokenStream {
     }
 }
 
+/// FIXME Derive into an active model
 #[proc_macro_derive(DeriveIntoActiveModel, attributes(sea_orm))]
 pub fn derive_into_active_model(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as DeriveInput);
@@ -92,6 +174,18 @@ pub fn derive_into_active_model(input: TokenStream) -> TokenStream {
         .into()
 }
 
+/// Models that a user can override
+/// ### Usage
+///
+/// ```
+/// use sea_orm::entity::prelude::*;
+///
+/// #[derive(Clone, Debug, PartialEq, DeriveModel, DeriveActiveModel, DeriveActiveModelBehavior,)]
+/// pub struct Model {
+///     pub id: i32,
+///     pub name: String,
+/// }
+/// ```
 #[proc_macro_derive(DeriveActiveModelBehavior)]
 pub fn derive_active_model_behavior(input: TokenStream) -> TokenStream {
     let DeriveInput { ident, data, .. } = parse_macro_input!(input);
@@ -102,6 +196,16 @@ pub fn derive_active_model_behavior(input: TokenStream) -> TokenStream {
     }
 }
 
+/// Convert a query result into the corresponding Model.
+/// ### Usage
+///
+/// ```
+///  #[derive(Debug, FromQueryResult)]
+///    struct SelectResult {
+///        name: String,
+///        num_of_fruits: i32,
+///    }
+/// ```
 #[proc_macro_derive(FromQueryResult)]
 pub fn derive_from_query_result(input: TokenStream) -> TokenStream {
     let DeriveInput { ident, data, .. } = parse_macro_input!(input);
@@ -112,6 +216,25 @@ pub fn derive_from_query_result(input: TokenStream) -> TokenStream {
     }
 }
 
+/// The DeriveRelation derive macro will implement RelationTrait for Relation.
+/// ### Usage
+/// ```
+/// #[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
+/// pub enum Relation {
+///    #[sea_orm(
+///         belongs_to = "super::cake::Entity",
+///         from = "Column::CakeId",
+///         to = "super::cake::Column::Id"
+///     )]
+///     Cake,
+///     #[sea_orm(
+///         belongs_to = "super::cake_expanded::Entity",
+///         from = "Column::CakeId",
+///         to = "super::cake_expanded::Column::Id"
+///     )]
+///     CakeExpanded,
+/// }
+/// ```
 #[proc_macro_derive(DeriveRelation, attributes(sea_orm))]
 pub fn derive_relation(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as DeriveInput);