From eed8b7c51ea2cdb64d12342691714f77612497aa Mon Sep 17 00:00:00 2001
From: Billy Chan <ccw.billy.123@gmail.com>
Date: Wed, 20 Oct 2021 15:06:23 +0800
Subject: [PATCH] Add docs

---
 sea-orm-macros/src/lib.rs | 23 ++++++++++++++++
 src/entity/active_enum.rs | 56 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+)

diff --git a/sea-orm-macros/src/lib.rs b/sea-orm-macros/src/lib.rs
index ccba2fab..f8503756 100644
--- a/sea-orm-macros/src/lib.rs
+++ b/sea-orm-macros/src/lib.rs
@@ -102,6 +102,29 @@ pub fn derive_active_model_behavior(input: TokenStream) -> TokenStream {
     }
 }
 
+/// A derive macro to implement `sea_orm::ActiveEnum` trait for enums.
+///
+/// # Limitations
+///
+/// This derive macros can only be used on enums.
+///
+/// # Macro Attributes
+///
+/// All macro attributes listed below have to be annotated in the form of `#[sea_orm(attr = value)]`.
+///
+/// - For enum
+///     - `rs_type`: Define `ActiveEnum::Value`
+///         - Possible values: `String`, `i8`, `i16`, `i32`, `i64`, `u8`, `u16`, `u32`, `u64`
+///         - Note that value has to be passed as string, i.e. `rs_type = "i8"`
+///     - `db_type`: Define `ColumnType` returned by `ActiveEnum::db_type()`
+///         - Possible values: all available enum variants of `ColumnType`, e.g. `String(None)`, `String(Some(1))`, `Integer`
+///         - Note that value has to be passed as string, i.e. `db_type = "Integer"`
+///
+/// - For enum variant
+///     - `string_value` or `num_value`:
+///         - For `string_value`, value should be passed as string, i.e. `string_value = "A"`
+///         - For `num_value`, value should be passed as integer, i.e. `num_value = 1` or `num_value = 1i32`
+///         - Note that only one of it can be specified, and all variants of an enum have to annotate with the same `*_value` macro attribute
 #[proc_macro_derive(DeriveActiveEnum, attributes(sea_orm))]
 pub fn derive_active_enum(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as DeriveInput);
diff --git a/src/entity/active_enum.rs b/src/entity/active_enum.rs
index b41779eb..c0453dda 100644
--- a/src/entity/active_enum.rs
+++ b/src/entity/active_enum.rs
@@ -9,6 +9,62 @@ use sea_query::{Nullable, Value, ValueType};
 ///
 /// # Examples
 ///
+/// Implementing it manually versus using the derive macro [DeriveActiveEnum](sea_orm_macros::DeriveActiveEnum).
+///
+/// > See [DeriveActiveEnum](sea_orm_macros::DeriveActiveEnum) for the full specification of macro attributes.
+///
+/// ```rust
+/// // Using the derive macro
+/// #[derive(Debug, PartialEq, DeriveActiveEnum)]
+/// #[sea_orm(rs_type = "String", db_type = "String(Some(1))")]
+/// pub enum DeriveCategory {
+///     #[sea_orm(string_value = "B")]
+///     Big,
+///     #[sea_orm(string_value = "S")]
+///     Small,
+/// }
+///
+/// // Implementing it manually
+/// #[derive(Debug, PartialEq)]
+/// pub enum Category {
+///     Big,
+///     Small,
+/// }
+///
+/// impl ActiveEnum for Category {
+///     // The macro attribute `rs_type` is being pasted here
+///     type Value = String;
+///
+///     // Will be atomically generated by `DeriveActiveEnum`
+///     fn to_value(&self) -> Self::Value {
+///         match self {
+///             Self::Big => "B",
+///             Self::Small => "S",
+///         }
+///         .to_owned()
+///     }
+///
+///     // Will be atomically generated by `DeriveActiveEnum`
+///     fn try_from_value(v: &Self::Value) -> Result<Self, DbErr> {
+///         match v.as_ref() {
+///             "B" => Ok(Self::Big),
+///             "S" => Ok(Self::Small),
+///             _ => Err(DbErr::Query(format!(
+///                 "unexpected value for Category enum: {}",
+///                 v
+///             ))),
+///         }
+///     }
+///
+///     fn db_type() -> ColumnDef {
+///         // The macro attribute `db_type` is being pasted here
+///         ColumnType::String(Some(1)).def()
+///     }
+/// }
+/// ```
+///
+/// Using [ActiveEnum] on Model.
+///
 /// ```
 /// use sea_orm::entity::prelude::*;
 ///