Add documentation in lib.rs

Author: greyblake

kinded/src/lib.rs

@@ -1,3 +1,129 @@
+//! # Kinded
+//!
+//! Generate Rust enum kind types without boilerplate.
+//!
+//! ## Get Started
+//!
+//! ```
+//! use kinded::Kinded;
+//!
+//! #[derive(Kinded)]
+//! enum Drink {
+//!     Mate,
+//!     Coffee(String),
+//!     Tea { variety: String, caffeine: bool }
+//! }
+//!
+//! let drink = Drink::Coffee("Espresso".to_owned());
+//! assert_eq!(drink.kind(), DrinkKind::Coffee);
+//! ```
+//!
+//! Note, the definition of `DrinkKind` enum was generated automatically as well as `Drink::kind()` method.
+//!
+//! ## Kinded trait
+//!
+//! The library provides `Kinded` trait:
+//!
+//! ```rs
+//! pub trait Kinded {
+//!     type Kind: PartialEq + Eq + Debug + Clone + Copy;
+//!
+//!     fn kind(&self) -> Self::Kind;
+//! }
+//! ```
+//!
+//! From the example above, the derived implementation of `Kinded` for `Drink` resembles the following:
+//!
+//! ```ignore
+//! impl Kinded for Drink {
+//!     type Kind = DrinkKind;
+//!
+//!     fn kind(&self) -> DrinkKind {
+//!         match self {
+//!             Drink::Mate => DrinkKind::Mate,
+//!             Drink::Coffee(..) => DrinkKind::Coffee,
+//!             Drink::Tea { .. } => DrinkKind::Tea,
+//!         }
+//!     }
+//! }
+//! ```
+//!
+//! The `Kinded` trait allows to build abstract functions that can be used with different enum types.
+//!
+//! ## Attributes
+//!
+//! ### Custom kind type name
+//!
+//! By default the kind type name is generated by adding postfix `Kind` to the original enum name.
+//! This can be customized with `kind = ` attribute:
+//!
+//! ```
+//! use kinded::Kinded;
+//!
+//! #[derive(Kinded)]
+//! #[kinded(kind = SimpleDrink)]
+//! enum Drink {
+//!     Mate,
+//!     Coffee(String),
+//!     Tea { variety: String, caffeine: bool }
+//! }
+//!
+//! assert_eq!(Drink::Mate.kind(), SimpleDrink::Mate);
+//! ```
+//!
+//! ### Derive traits
+//!
+//! By default the kind type implements the following traits: `Debug`, `Clone`, `Copy`, `PartialEq`, `Eq`, `From<T>`, `From<&T>`.
+//!
+//! Extra traits can be derived with `derive(..)` attribute:
+//!
+//! ```
+//! use kinded::Kinded;
+//! use std::collections::HashSet;
+//!
+//! #[derive(Kinded)]
+//! #[kinded(derive(Hash))]
+//! enum Drink {
+//!     Mate,
+//!     Coffee(String),
+//!     Tea { variety: String, caffeine: bool }
+//! }
+//!
+//! let mut drink_kinds = HashSet::new();
+//! drink_kinds.insert(DrinkKind::Mate);
+//! ```
+//!
+//! ## A note about enum-kinds
+//!
+//! There is a very similar crate [enum-kinds](https://github.com/Soft/enum-kinds) that does almost the same job.
+//!
+//! The main difference between `kinded` and `enum-kinds` crate is that `kinded` provides the `Kinded` trait, on top of which
+//! users can implement abstract functions and use them with different enum types.
+//!
+//! Another minor difference is that apart from `From<T>` and `From<&T>` conversions, `kidned` also implements `kind()` function on the enum type.
+//!
+//! ## A note about the war in Ukraine 🇺🇦
+//!
+//! Today I live in Berlin, I have the luxury to live a physically safe life.
+//! But I am Ukrainian. The first 25 years of my life I spent in [Kharkiv](https://en.wikipedia.org/wiki/Kharkiv),
+//! the second-largest city in Ukraine, 60km away from the border with russia. Today about [a third of my home city is destroyed](https://www.youtube.com/watch?v=ihoufBFSZds) by russians.
+//! My parents, my relatives and my friends had to survive the artillery and air attack, living for over a month in basements.
+//!
+//! Some of them have managed to evacuate to EU. Some others are trying to live "normal lifes" in Kharkiv, doing there daily duties.
+//! And some are at the front line right now, risking their lives every second to protect the rest.
+//!
+//! I encourage you to donate to [Charity foundation of Serhiy Prytula](https://prytulafoundation.org/en).
+//! Just pick the project you like and donate. This is one of the best-known foundations, you can watch a [little documentary](https://www.youtube.com/watch?v=VlmWqoeub1Q) about it.
+//! Your contribution to the Ukrainian military force is a contribution to my calmness, so I can spend more time developing the project.
+//!
+//! Thank you.
+//!
+//!
+//! ## License
+//!
+//! MIT © [Serhii Potapov](https://www.greyblake.com)
+
+
 pub use kinded_macros::Kinded;
 use std::fmt::Debug;
 

kinded_macros/src/lib.rs

@@ -1,3 +1,12 @@
+//! # Kinded
+//!
+//! Generate Rust enum kind types without boilerplate.
+//!
+//! Author: [Serhii Potapov](https://www.greyblake.com/)
+//!
+//! This is a supporting macro crate, that should not be used directly.
+//! For the documentation please refer to [kinded](https://docs.rs/kinded/) crate.
+
 pub(crate) mod gen;
 pub(crate) mod models;
 pub(crate) mod parse;