From a2116293aa9c46e2551e78fb344bc99aa3dc943d Mon Sep 17 00:00:00 2001 From: Ted Driggs Date: Mon, 15 May 2017 17:27:23 -0700 Subject: [PATCH] Add docs and bump version --- Cargo.toml | 8 ++++---- core/Cargo.toml | 2 +- macro/Cargo.toml | 4 ++-- src/lib.rs | 50 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 57 insertions(+), 7 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 7af460b..957afb3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,9 +1,9 @@ [package] name = "darling" -version = "0.1.0" +version = "0.1.1" authors = ["Ted Driggs "] repository = "https://github.com/TedDriggs/darling" -documentation = "https://docs.rs/darling/0.1.0" +documentation = "https://docs.rs/darling/0.1.1" description = """ A proc-macro library for reading attributes into structs when implementing custom derives. @@ -12,8 +12,8 @@ license = "MIT" readme = "README.md" [dependencies] -darling_core = { version = "=0.1.0", path = "core" } -darling_macro = { version = "=0.1.0", path = "macro" } +darling_core = { version = "=0.1.1", path = "core" } +darling_macro = { version = "=0.1.1", path = "macro" } [dev-dependencies] syn = "0.11" diff --git a/core/Cargo.toml b/core/Cargo.toml index c4681c6..ab5a79a 100644 --- a/core/Cargo.toml +++ b/core/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "darling_core" -version = "0.1.0" +version = "0.1.1" authors = ["Ted Driggs "] repository = "https://github.com/TedDriggs/darling" description = """ diff --git a/macro/Cargo.toml b/macro/Cargo.toml index 30a9804..f3358da 100644 --- a/macro/Cargo.toml +++ b/macro/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "darling_macro" -version = "0.1.0" +version = "0.1.1" authors = ["Ted Driggs "] repository = "https://github.com/TedDriggs/darling" description = """ @@ -15,4 +15,4 @@ proc-macro = true [dependencies] quote = "0.3.8" syn = "0.11.11" -darling_core = { version = "=0.1.0", path = "../core" } \ No newline at end of file +darling_core = { version = "=0.1.1", path = "../core" } \ No newline at end of file diff --git a/src/lib.rs b/src/lib.rs index 6e866dd..6898148 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,53 @@ +//! # Darling +//! Darling is a tool for declarative attribute parsing in proc macro implementations. +//! +//! +//! ## Design +//! Darling takes considerable design inspiration from [`serde`]. A data structure that can be +//! read from any attribute implements `FromMetaItem` (or has an implementation automatically +//! generated using `derive`). Any crate can provide `FromMetaItem` implementations, even one not +//! specifically geared towards proc-macro authors. +//! +//! Proc-macro crates should provide their own structs which implement or derive `FromDeriveInput` and +//! `FromField` to gather settings relevant to their operation. +//! +//! ## Attributes +//! There are a number of attributes that `darling` exposes to enable finer-grained control over the code +//! it generates. +//! +//! * **Field renaming**: You can use `#[darling(rename="new_name")]` on a field to change the name Darling looks for. +//! You can also use `#[darling(rename_all="...")]` at the struct or enum level to apply a casing rule to all fields or variants. +//! * **Map function**: You can use `#[darling(map="path::to::function")]` to run code on a field before its stored in the struct. +//! * **Default values**: You can use `#[darling(default)]` at the type or field level to use that type's default value to fill +//! in values not specified by the caller. +//! * **Skipped fields**: You can skip a variant or field using `#[darling(skip)]`. Fields marked with this will fall back to +//! `Default::default()` for their value, but you can override that with an explicit default or a value from the type-level default. +//! +//! ## Forwarded Fields +//! The traits `FromDeriveInput` and `FromField` support forwarding fields from the input AST directly +//! to the derived struct. These fields are matched up by identifier **before** `rename` attribute values are +//! considered. The deriving struct is responsible for making sure the types of fields it does declare match this +//! table. +//! +//! A deriving struct is free to include or exclude any of the fields below. +//! +//! ### `FromDeriveInput` +//! |Field name|Type|Meaning| +//! |---|---|---| +//! |`ident`|`syn::Ident`|The identifier of the passed-in type| +//! |`vis`|`syn::Visibility`|The visibility of the passed-in type| +//! |`generics`|`syn::Generics`|The generics of the passed-in type| +//! |`body`|`darling::util::Body`|The body of the passed-in type| +//! |`attrs`|`Vec`|The forwarded attributes from the passed in type. These are controlled using the `forward_attrs` attribute.| +//! +//! ### `FromField` +//! |Field name|Type|Meaning| +//! |---|---|---| +//! |`ident`|`syn::Ident`|The identifier of the passed-in field| +//! |`vis`|`syn::Visibility`|The visibility of the passed-in field| +//! |`ty`|`syn::Ty`|The type of the passed-in field| +//! |`attrs`|`Vec`|The forwarded attributes from the passed in field. These are controlled using the `forward_attrs` attribute.| + extern crate core; extern crate darling_core;