doc: library-level documentation

Author: Pscheidl

enum-collections/Cargo.toml

@@ -14,8 +14,11 @@ documentation = "https://docs.rs/enum-collections"
 
 [features]
 default = ["debug", "eq"]
+# `std::fmt::Debug` implementation for EnumMap. Requires keys to be `Debug` as well.
 debug = ["variants"] # Array of all variants must be available at runtime to generate keys in the Debug output
+# `std::cmp::Eq` implementation for EnumMap. Requires keys to be `Eq` as well.
 eq = []
+# Generates a static array of all variants for the EnumMap. This is required for the `Debug` implementation.
 variants = ["enum-collections-macros/variants"]
 
 [dependencies]

enum-collections/src/enummap.rs

@@ -101,7 +101,7 @@ mod macro_test {
 /// # Examples
 ///
 /// ```
-/// use enum_collections::{EnumMap, Enumerated};
+/// use enum_collections::{EnumMap, Enumerated, em_default, em};
 ///
 /// #[derive(Enumerated)]
 /// pub enum Letter {
@@ -116,6 +116,22 @@ mod macro_test {
 /// enum_map[Letter::A] = 42;
 /// assert_eq!(42, enum_map[Letter::A]);
 ///
+/// // Construction using macros
+/// // (Key type, Value type, Key=>Value pairs)
+/// let enum_map = em!(Letter, i32,  A=>42, B=>24); // All values set explicitly
+/// assert_eq!(42, enum_map[Letter::A]);
+/// assert_eq!(24, enum_map[Letter::B]);
+///
+/// // (Key type, Value type, optional Key=>Value pairs)
+/// let enum_map = em_default!(Letter, i32, A => 42); // Default used for missing values
+/// assert_eq!(42, enum_map[Letter::A]);
+/// assert_eq!(i32::default(), enum_map[Letter::B]);
+///
+/// let enum_map = em_default!(Letter, i32,); // All default
+/// assert_eq!(i32::default(), enum_map[Letter::A]);
+/// assert_eq!(i32::default(), enum_map[Letter::B]);
+///
+///
 /// // Constructor with default values
 /// let enum_map_default = EnumMap::<Letter, i32, { Letter::SIZE }>::new_default();
 /// assert_eq!(0, enum_map_default[Letter::A]);

enum-collections/src/lib.rs

@@ -1,3 +1,20 @@
+//!# Enum collections
+//!
+//! See [EnumMap] for usage details.
+//!
+//! A map of enum variants to values. EnumMap is a fixed-size map, where each variant of the enum is mapped to a value.
+//! This implementation of EnumMap uses **safe Rust** only and is a a zero-cost abstraction over an array (**const-sized**),
+//! where the index of the array corresponds to the position of the variant in the enum.
+//!
+//! Because it is a thin wrapper over an array, it is stack-allocated by default. Simply `std::boxed::Box`ing it will move it to the heap, at the caller's discretion.
+//!- Indexed by enum variants.
+//!- IndexMut by enum variants.
+//!- Debug if the enum is Debug.
+//!- PartialEq if the value is PartialEq. Same for Eq.
+//!
+//!Debug and Eq are optional features. They are enabled by default.
+//!
+//!
 mod enumerated;
 mod enummap;