improve docs

1 files changed, 56 insertions, 13 deletions

diff --git a/fondant/src/lib.rs b/fondant/src/lib.rs
index d5758dc..ddf29c9 100644
--- a/fondant/src/lib.rs
+++ b/fondant/src/lib.rs
@@ -1,22 +1,42 @@
+//! # fondant
+//!
+//! [Documentation](https://docs.rs/fondant/) ·
+//! [Architecture](#Architecture) · [Usage](#Usage) ·
+//! [Customization](#Customization) · [Todo](#Todo)
+//!
 //! `fondant` is a macro based library to take the boilerplate out of
-//! configuration handling. Most of `fondant` is based off the `confy` crate.
+//! configuration handling. All you need to do is derive the
+//! `Configure` trait on your struct, and `fondant` will decide
+//! where to store it and and how to do so safely.
 //!
+//! Most of `fondant` is based off the `confy` crate.
 //! `fondant` adds a couple of extra features:
 //!
 //!  - support for json, yaml and toml
 //!  - support for custom config paths
 //!  - support for custom config file names
 //!
-//!  ### Sample usage
+//! ### Architecture
 //!
-//! ```
+//! `fondant` is split into 3 separate crates:
+//!
+//!  - `fondant_deps`: external crates and utils that `fondant` requires
+//!  - `fondant_derive`: core macro definitions
+//!  - `fondant`: the user facing library that brings it all together
+//!
+//! This slightly strange architecture arose because of some
+//! limitations with proc-macro crates and strict cyclic
+//! dependencies in cargo. All you need is the `fondant` crate.
+//!
+//! ### Usage
+//!
+//! ```rust
 //! // the struct has to derive Serialize, Deserialize and Default
 //! #[derive(Configure, Serialize, Deserialize, Default)]
 //! #[config_file = "config.toml"]
-//! // |
-//! // `-- this attribute sets the file name to "config.toml"
-//! // `-- the file format to "toml"
-//! // `-- the file path to "default" (read the notes below)
+//! // `config_file` attribute sets the file name to "config.toml"
+//! // the file format to "toml"
+//! // and the file path to "default" (read the notes below)
 //! struct AppConfig {
 //!     version: u32,
 //!     port: u32,
@@ -24,7 +44,8 @@
 //! }
 //!
 //! fn main() {
-//!     // use `load` (associated method) to load the config file
+//!     // use `load` to load the config file
+//!     // loads in Default::default if it can't find one
 //!     let mut conf = AppConfig::load().unwrap();
 //!
 //!     // do stuff with conf
@@ -34,6 +55,7 @@
 //!     conf.store().unwrap();
 //! }
 //! ```
+//!
 //! **Notes**:  
 //!  - `load` returns `Default::default` if the config file is not present, and stores
 //!  a serialized `Default::default` at the specified path
@@ -46,7 +68,7 @@
 //!
 //! Set your own filename, for ex.: `apprc`
 //!
-//! ```
+//! ```rust
 //! #[derive(Configure, Serialize, Deserialize, Default)]
 //! #[config_file = "apprc.toml"]
 //! struct AppConfig {
@@ -58,7 +80,8 @@
 //!
 //! Change file format to `yaml`, by changing the file extension.
 //! Supported extensions are `yaml`, `toml`, `json`:
-//! ```
+//!
+//! ```rust
 //! #[derive(Configure, Serialize, Deserialize, Default)]
 //! #[config_file = "config.yaml"]
 //! struct AppConfig {
@@ -68,9 +91,10 @@
 //! // effective format: yaml
 //! ```
 //!
-//! Override the default config path, for ex.: the home directory
-//! (it is not recommended to override config path):
-//! ```
+//! Override the default config path (not recommended),
+//! for ex.: the home directory:
+//!
+//! ```rust
 //! #[derive(Configure, Serialize, Deserialize, Default)]
 //! #[config_file = "~/.apprc.json"]
 //! struct AppConfig {
@@ -79,6 +103,25 @@
 //! // effective path: $HOME/.apprc.json
 //! // effective format: json
 //! ```
+//!
+//! Fondant meshes well with Serde, for ex.:
+//! ```rust
+//! #[derive(Configure, Serialize, Deserialize, Default)]
+//! #[config_file = "config.toml"]
+//! struct Madagascar {
+//!     #[serde(skip)]
+//!     rating: u32,
+//!
+//!     name: String,
+//!     penguins: u32,
+//! }
+//! ```
+//!
+//! Above snippet produces this config file:
+//! ```toml
+//! name = 'Central Park Zoo'
+//! penguins = 4
+//! ```
 
 pub use fondant_deps::fondant_exports;
 pub use fondant_deps::Configure;