add doc to readme

2 files changed, 86 insertions, 30 deletions

diff --git a/fondant_derive/.gitignore b/fondant_derive/.gitignore
deleted file mode 100644
index 088ba6b..0000000
--- a/fondant_derive/.gitignore
+++ /dev/null
@@ -1,10 +0,0 @@
-# Generated by Cargo
-# will have compiled files and executables
-/target/
-
-# Remove Cargo.lock from gitignore if creating an executable, leave it for libraries
-# More information here https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html
-Cargo.lock
-
-# These are backup files generated by rustfmt
-**/*.rs.bk
diff --git a/readme.md b/readme.md
index 3445327..9f239c5 100644
--- a/readme.md
+++ b/readme.md
@@ -1,47 +1,113 @@
 # fondant
 
-> an experimental, macro-only, boilerplate free, configuration management library
+`fondant` is a macro based library to take the boilerplate out of
+configuration handling. Most of `fondant` is based off the `confy` crate.
 
-### example
+`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
 
 ```rust
-// derive the `Configure` trait, and specify the
-// `config_file` attribute
-#[derive(Configure, Default, Serialize, Deserialize)]
+// 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)
 struct AppConfig {
-    -- snip --
+    version: u32,
+    port: u32,
+    username: String,
 }
 
-// `Configure` exposes `load` and `store`
 fn main() {
-    let mut config = AppConfig::load().unwrap();
-    config.version = 2;
-    config.path = "/home/np".to_string();
-    config.store();
+    // use `load` (associated method) to load the config file
+    let mut conf = AppConfig::load().unwrap();
+
+    // do stuff with conf
+    conf.version = 2;
+
+    // call `store` to save changes
+    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
+ - the "default" config path varies by platform:
+    * GNU/Linux: `$XDG_CONFIG_HOME/my_cool_crate/config.toml` (follows xdg spec)
+    * MacOS: `$HOME/Library/Preferences/my_cool_crate/config.toml`
+    * Windows: `{FOLDERID_RoamingAppData}\_project_path_\config`
+
+### Customization
+
+Set your own filename, for ex.: `apprc`
+
+```rust
+#[derive(Configure, Serialize, Deserialize, Default)]
+#[config_file = "apprc.toml"]
+struct AppConfig {
+    // -- snip --
 }
+// effective path: $XDG_CONFIG_HOME/my_cool_crate/apprc.toml
+// effective format: toml
 ```
 
-You can specify a path to be used, unless you want to stick
-with the defaults:
+Change file format to `yaml`, by changing the file extension.
+Supported extensions are `yaml`, `toml`, `json`:
 
 ```rust
-// load from and store in user's home directory
-#[config_file = "~/config.toml"]
+#[derive(Configure, Serialize, Deserialize, Default)]
+#[config_file = "config.yaml"]
+struct AppConfig {
+    // -- snip --
+}
+// effective path: $XDG_CONFIG_HOME/my_cool_crate/config.yaml
+// effective format: yaml
 ```
 
-`fondant` supports `yaml`, `toml` and `json`, defaults to
-`toml`:
+Override the default config path, for ex.: the home directory
+(it is not recommended to override config path):
+
+```rust
+#[derive(Configure, Serialize, Deserialize, Default)]
+#[config_file = "~/.apprc.json"]
+struct AppConfig {
+    // -- snip --
+}
+// 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"]
-#[config_file = "my_app_config.yaml"]
-#[config_file = "~/.app.conf.json"]
+struct Madagascar {
+    #[serde(skip)]
+    rating: u32,
+
+    name: String,
+    penguins: u32,
+}
+```
+
+Above snippet produces this config file:
+```toml
+name = 'Central Park Zoo'
+penguins = 4
 ```
 
 ### todo
 
  - [ ] improve error from trait impl
  - [ ] use `syn::Error` and `syn::Result` to report macro errors
- - [ ] write docs
+ - [x] write docs
  - [ ] bundle and publish to crates.io
+