Add readme and some documentation

Author: jmeggitt

Cargo.toml

@@ -1,12 +1,13 @@
 [package]
 name = "serde_flat_path"
-version = "0.1.0"
+version = "0.1.1"
 authors = ["Jasper Meggitt <[email protected]>"]
 description = "A macro for expanding long structure chains within serde"
 license = "MIT"
 edition = "2021"
 repository = "https://github.com/jmeggitt/serde_flat_path"
 keywords = ["serde", "flatten"]
+readme = "readme.md"
 
 [lib]
 proc-macro = true

readme.md

@@ -0,0 +1,58 @@
+# `serde_flat_path`
+This crate was designed to solve the problem of needing to manually create placeholder structs or untyped values (such
+as `serde_json::Value`). For example, take this json file:
+```json
+{
+  "title": "Foo",
+  "foo": true,
+  "config": {
+    "bar": {
+      "name": "foo bar"
+    }
+  }
+}
+```
+Using serde derive, you would likely arrive at something similar to the code shown below. As you can see, you may need
+to create separate structures for `config` and `bar` despite only containing a single field of interest each.
+```rust
+#[derive(Deserialize)]
+struct Foo {
+    title: String,
+    foo: bool,
+    config: FooConfig,
+}
+
+#[derive(Deserialize)]
+struct FooConfig {
+    bar: Bar,
+}
+
+#[derive(Deserialize)]
+struct Bar {
+    name: String,
+}
+```
+To solve this problem, this crate provides a macro for shortening a long path to a single field.
+```rust
+#[flat_path]
+#[derive(Deserialize)]
+struct Foo {
+    title: String,
+    foo: bool,
+    #[flat_path("config.bar.name")]
+    bar_name: String,
+}
+```
+
+## Usage
+`flat_path` can be applied to any named field within a `struct` or `enum`. The `#[flat_path]` attribute must be applied
+before the serialize/deserialize `#[derive(...)]` so that it can apply the necessary serde attributes before serde
+performs macro expansion for its derive macros. Similar to derive macros, the original type is not altered.
+
+For cases where field names contain `.` or additional verbosity is desired, `#[flat_path("a.b.c")]` may also be written
+as `#[flat_path(path = ["a", "b", "c"])]`. These two forms are equivalent and no distinction is made between regarding
+macro expansion.
+
+`#[serde(...)]` attributes are also moved from `#[flat_path(...)]` fields to the final field within the path. During
+this process, the order of attributes remains the same. 
+

src/lib.rs

@@ -1,3 +1,32 @@
+//! `flat_path` can be applied to any named field within a `struct` or `enum`. The `#[flat_path]`
+//! attribute must be applied before the serialize/deserialize `#[derive(...)]` so that it can apply
+//! the necessary serde attributes before serde performs macro expansion for its derive macros.
+//! Similar to derive macros, the original type is not altered.
+//!
+//! For cases where field names contain `.` or additional verbosity is desired,
+//! `#[flat_path("a.b.c")]` may also be written as `#[flat_path(path = ["a", "b", "c"])]`. These two
+//! forms are equivalent and no distinction is made between regarding macro expansion.
+//!
+//! `#[serde(...)]` attributes are also moved from `#[flat_path(...)]` fields to the final field
+//! within the path. During this process, the order of attributes remains the same.
+//!
+//! ```rust
+//! # use serde::{Serialize, Deserialize};
+//! # use serde_flat_path::flat_path;
+//! #[flat_path]
+//! #[derive(Serialize, Deserialize, Debug, Eq, PartialEq, Default)]
+//! #[serde(default)]
+//! pub struct Foo {
+//!     foo: bool,
+//!     #[flat_path(path=["a", "b", "c"])]
+//!     x: Option<u64>,
+//!     #[serde(rename="INDEX")]
+//!     index_number: u32,
+//! }
+//! ```
+//!
+//! For more examples see the repository's tests folder.
+
 use proc_macro::TokenStream;
 use proc_macro2::Span;
 use proc_macro2::{Ident, TokenStream as TokenStream2};
@@ -9,8 +38,10 @@ use syn::{
 };
 
 mod attr;
+
 use attr::*;
 
+/// For documentation go to the [crate] root page.
 #[proc_macro_attribute]
 pub fn flat_path(attr: TokenStream, input: TokenStream) -> TokenStream {
     match flat_path_impl(attr, input) {