diff --git a/src/entity/active_model.rs b/src/entity/active_model.rs index af1fc339..abf96014 100644 --- a/src/entity/active_model.rs +++ b/src/entity/active_model.rs @@ -57,25 +57,7 @@ where /// Enforces a set of constraints on any type performing an Create, Update or Delete operation. /// The type must also implement the [EntityTrait]. -/// #### Example -/// ``` -/// use sea_orm::entity::prelude::*; -/// -/// #[derive(Copy, Clone, Default, Debug, DeriveEntity)] -/// pub struct Entity; -/// -/// impl EntityName for Entity { -/// fn table_name(&self) -> &str { -/// "cake" -/// } -/// } -/// -/// #[derive(Clone, Debug, PartialEq, DeriveActiveModel)] -/// pub struct Model { -/// pub id: i32, -/// pub name: Option, -/// } -/// ``` +/// See module level docs [crate::entity] for a full example #[async_trait] pub trait ActiveModelTrait: Clone + Debug { /// Enforce the type to the constraints of the [EntityTrait] @@ -210,18 +192,30 @@ pub trait ActiveModelTrait: Clone + Debug { /// The type must also implement the [ActiveModelTrait] /// /// ### Example -/// ``` +/// ```ignore /// use sea_orm::entity::prelude::*; /// -/// /// Derive the active +/// // Use [DeriveEntity] to derive the EntityTrait automatically +/// #[derive(Copy, Clone, Default, Debug, DeriveEntity)] +/// pub struct Entity; +/// +/// /// The [EntityName] describes the name of a table +/// impl EntityName for Entity { +/// fn table_name(&self) -> &str { +/// "cake" +/// } +/// } +/// +/// // Derive the ActiveModel /// #[derive(Clone, Debug, PartialEq, DeriveModel, DeriveActiveModel)] /// pub struct Model { /// pub id: i32, /// pub name: String, -/// pub cake_id: Option, /// } -/// ``` +/// /// impl ActiveModelBehavior for ActiveModel {} +/// ``` +/// See module level docs [crate::entity] for a full example #[allow(unused_variables)] pub trait ActiveModelBehavior: ActiveModelTrait { /// Create a new ActiveModel with default values. Also used by `Default::default()`. diff --git a/src/entity/mod.rs b/src/entity/mod.rs index 08280326..76187def 100644 --- a/src/entity/mod.rs +++ b/src/entity/mod.rs @@ -1,125 +1,104 @@ -//! This modules contains types and traits for an Entity, ActiveMode, Model, PrimaryKey, ForeignKey and Relations. -//! -//! // An Entity -//! A unit struct implements [EntityTrait](crate::EntityTrait) representing a table in the database. -//! -//! This trait contains the properties of an entity including -//! -//! Table Name (implemented EntityName) -//! Column (implemented ColumnTrait) -//! Relation (implemented RelationTrait) -//! Primary Key (implemented PrimaryKeyTrait and PrimaryKeyToColumn) -//! -//! This trait also provides an API for CRUD actions -//! -//! Select: find, find_* -//! Insert: insert, insert_* -//! Update: update, update_* -//! Delete: delete, delete_* -//! -//! #### Example for creating an Entity, Model and ActiveModel -//! ``` -//! use sea_orm::entity::prelude::*; -//! -//! // Use [DeriveEntity] to derive the EntityTrait automatically -//! #[derive(Copy, Clone, Default, Debug, DeriveEntity)] -//! pub struct Entity; -//! -//! /// The [EntityName] describes the name of a table -//! impl EntityName for Entity { -//! fn table_name(&self) -> &str { -//! "cake" -//! } -//! } -//! -//! // Create a Model for the Entity through [DeriveModel]. -//! // The `Model` handles `READ` operations on a table in a database. -//! // The [DeriveActiveModel] creates a way to perform `CREATE` , `READ` and `UPDATE` operations -//! // in a database -//! -//! #[derive(Clone, Debug, PartialEq, DeriveModel, DeriveActiveModel)] -//! pub struct Model { -//! pub id: i32, -//! pub name: Option, -//! } -//! -//! // Use the [DeriveColumn] to create a Column for an the table called Entity -//! // The [EnumIter] which creates a new type that iterates of the variants of a Column. -//! #[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)] -//! pub enum Column { -//! Id, -//! Name, -//! } -//! -//! // Create a PrimaryKey for the Entity using the [PrimaryKeyTrait] -//! // The [EnumIter] which creates a new type that iterates of the variants of a PrimaryKey. -//! #[derive(Copy, Clone, Debug, EnumIter, DerivePrimaryKey)] -//! pub enum PrimaryKey { -//! Id, -//! } -//! -//! // Or implement the [PrimaryKeyTrait] manually instead of using the macro [DerivePrimaryKey] -//! impl PrimaryKeyTrait for PrimaryKey { -//! type ValueType = i32; -//! -//! fn auto_increment() -> bool { -//! true -//! } -//! } -//! -//! // Create a Relation for the Entity -//! #[derive(Copy, Clone, Debug, EnumIter)] -//! #[sea_orm( -//! // The relation belongs to `Entity` type -//! belongs_to = "Entity", -//! from = "Column::FruitId", -//! to = "Column::Id" -//! )] -//! pub enum Relation { -//! Fruit, -//! } -//! -//! // Create the properties of a Column in an Entity ensuring that calling -//! // Column::def() yields a Column definition as defined in [ColumnDef] -//! impl ColumnTrait for Column { -//! type EntityName = Entity; -//! fn def(&self) -> ColumnDef { -//! match self { -//! Self::Id => ColumnType::Integer.def(), -//! Self::Name => ColumnType::Text.def().null(), -//! } -//! } -//! } -//! -//! // Implement the set of constraints for creating a Relation as defined in the [RelationTrait] -//! impl RelationTrait for Relation { -//! fn def(&self) -> RelationDef { -//! match self { -//! Self::Fruit => Entity::has_many(super::fruit::Entity).into(), -//! } -//! } -//! } -//! -//! impl Related for Entity { -//! fn to() -> RelationDef { -//! Relation::Fruit.def() -//! } -//! } -//! -//! impl Related for Entity { -//! fn to() -> RelationDef { -//! super::cake_filling::Relation::Filling.def() -//! } -//! fn via() -> Option { -//! Some(super::cake_filling::Relation::Cake.def().rev()) -//! } -//! } -//! -//! // Implement user defined operations for CREATE, UPDATE and DELETE operations -//! // to create an ActiveModel using the [ActiveModelBehavior] -//! impl ActiveModelBehavior for ActiveModel {} -//! ``` - +/// This modules contains types and traits for an Entity, ActiveMode, Model, PrimaryKey, ForeignKey and Relations. +/// +/// // An Entity +/// A unit struct implements [EntityTrait](crate::EntityTrait) representing a table in the database. +/// +/// This trait contains the properties of an entity including +/// +/// - The Table Name which is implemented by [EntityName](crate::EntityName) +/// - The Column which is implemented by [ColumnTrait](crate::ColumnTrait) +/// - A Relation which is implemented by [RelationTrait](crate::RelationTrait) +/// - The Primary Key which is implemented by [PrimaryKeyTrait](crate::PrimaryKeyTrait) +/// and [PrimaryKeyToColumn](crate::PrimaryKeyToColumn) +/// +/// This trait also provides an API for CRUD actions +/// +/// #### Example for creating an Entity, Model and ActiveModel +/// ``` +/// #[cfg(feature = "macros")] +/// +/// # use crate::entity::prelude::*; +/// # use sea_orm_macros::*; +/// use sea_orm::ActiveModelBehavior; +/// use sea_orm::RelationDef; +/// use sea_orm::RelationTrait; +/// use sea_orm::ColumnType; +/// use sea_orm::ColumnDef; +/// use sea_orm::ColumnTrait; +/// use sea_orm::PrimaryKeyTrait; +/// use sea_orm::EntityName; +/// +/// // Use [DeriveEntity] to derive the EntityTrait automatically +/// #[derive(Copy, Clone, Default, Debug, DeriveEntity)] +/// pub struct Entity; +/// +/// /// The [EntityName] describes the name of a table +/// impl EntityName for Entity { +/// fn table_name(&self) -> &str { +/// "filling" +/// } +/// } +/// +/// // Create a Model for the Entity through [DeriveModel]. +/// // The `Model` handles `READ` operations on a table in a database. +/// // The [DeriveActiveModel] creates a way to perform `CREATE` , `READ` and `UPDATE` operations +/// // in a database +/// #[derive(Clone, Debug, PartialEq, DeriveModel, DeriveActiveModel)] +/// pub struct Model { +/// pub id: i32, +/// pub name: String, +/// } +/// +/// // Use the [DeriveColumn] to create a Column for an the table called Entity +/// // The [EnumIter] which creates a new type that iterates of the variants of a Column. +/// #[derive(Copy, Clone, Debug, EnumIter, DeriveColumn)] +/// pub enum Column { +/// Id, +/// Name, +/// } +/// +/// // Create a PrimaryKey for the Entity using the [PrimaryKeyTrait] +/// // The [EnumIter] which creates a new type that iterates of the variants of a PrimaryKey. +/// #[derive(Copy, Clone, Debug, EnumIter, DerivePrimaryKey)] +/// pub enum PrimaryKey { +/// Id, +/// } +/// +/// // Or implement the [PrimaryKeyTrait] manually instead of using the macro [DerivePrimaryKey] +/// impl PrimaryKeyTrait for PrimaryKey { +/// type ValueType = i32; +/// +/// fn auto_increment() -> bool { +/// true +/// } +/// } +/// +/// +/// #[derive(Copy, Clone, Debug, EnumIter)] +/// pub enum Relation {} +/// +/// impl ColumnTrait for Column { +/// type EntityName = Entity; +/// +/// fn def(&self) -> ColumnDef { +/// match self { +/// Self::Id => ColumnType::Integer.def(), +/// Self::Name => ColumnType::String(None).def(), +/// } +/// } +/// } +/// +/// // Create a Relation for the Entity +/// impl RelationTrait for Relation { +/// fn def(&self) -> RelationDef { +/// panic!() +/// } +/// } +/// // Implement user defined operations for CREATE, UPDATE and DELETE operations +/// // to create an ActiveModel using the [ActiveModelBehavior] +/// impl ActiveModelBehavior for ActiveModel {} +/// +/// ``` mod active_model; mod base_entity; mod column; diff --git a/src/entity/primary_key.rs b/src/entity/primary_key.rs index 39969888..d4075a2c 100644 --- a/src/entity/primary_key.rs +++ b/src/entity/primary_key.rs @@ -9,7 +9,7 @@ use std::fmt::Debug; /// A primary key can be derived manually /// /// ### Example -/// ``` +/// ```text /// use sea_orm::entity::prelude::*; /// /// #[derive(Copy, Clone, Debug, EnumIter)] @@ -28,7 +28,7 @@ use std::fmt::Debug; /// Alternatively, use derive macros to automatically implement the trait for a Primary Key /// /// ### Example -/// ``` +/// ```text /// use sea_orm::entity::prelude::*; /// /// #[derive(Copy, Clone, Debug, EnumIter, DerivePrimaryKey)] @@ -36,6 +36,7 @@ use std::fmt::Debug; /// Id, /// } /// ``` +/// See module level docs [crate::entity] for a full example pub trait PrimaryKeyTrait: IdenStatic + Iterable { #[allow(missing_docs)] type ValueType: Sized