From 4605fd18d51fa88813f086b86bd4e90756a172a8 Mon Sep 17 00:00:00 2001 From: Pantonshire Date: Fri, 21 May 2021 14:41:21 +0100 Subject: [PATCH] Documentation --- README.md | 2 +- enumscribe/Cargo.toml | 1 + enumscribe/src/lib.rs | 57 ++++++++++++++++++++++++++++-------- enumscribe_derive/Cargo.toml | 1 + enumscribe_derive/src/lib.rs | 5 ++-- 5 files changed, 50 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index c933a0f..93392d6 100644 --- a/README.md +++ b/README.md @@ -68,7 +68,7 @@ enum Website { // Note that we don't need to use an Option anymore! assert_eq!(Website::unscribe("github.com"), Website::Github); -// Unbelievably, there exist websites other than github and crates.io +// Unbelievably, websites exist other than github and crates.io assert_eq!(Website::unscribe("stackoverflow.com"), Website::Other("stackoverflow.com".to_owned())); // We can't scribe to a &'static str anymore, so we use a Cow<'static, str> instead diff --git a/enumscribe/Cargo.toml b/enumscribe/Cargo.toml index 9a5c5ac..fc8801e 100644 --- a/enumscribe/Cargo.toml +++ b/enumscribe/Cargo.toml @@ -5,6 +5,7 @@ authors = ["Tom Panton "] edition = "2018" license = "MIT" repository = "https://github.com/Pantonshire/enumscribe" +readme = "../README.md" description = "Procedural macros for converting between enums and strings" [dependencies] diff --git a/enumscribe/src/lib.rs b/enumscribe/src/lib.rs index d433a54..be18faa 100644 --- a/enumscribe/src/lib.rs +++ b/enumscribe/src/lib.rs @@ -63,15 +63,19 @@ //! } //! //! // Note that we don't need to use an Option anymore! -//! assert_eq!(Website::unscribe("github.com"), Website::Github); +//! assert_eq!(Website::unscribe("github.com"), +//! Website::Github); //! -//! // Unbelievably, there exist websites other than github and crates.io -//! assert_eq!(Website::unscribe("stackoverflow.com"), Website::Other("stackoverflow.com".to_owned())); +//! // Unbelievably, websites exist other than github and crates.io +//! assert_eq!(Website::unscribe("stackoverflow.com"), +//! Website::Other("stackoverflow.com".to_owned())); //! //! // We can't scribe to a &'static str anymore, so we use a Cow<'static, str> instead -//! assert_eq!(Website::Github.scribe(), Cow::Borrowed::<'static, str>("github.com")); +//! assert_eq!(Website::Github.scribe(), +//! Cow::Borrowed::<'static, str>("github.com")); //! -//! assert_eq!(Website::Other("owasp.org".to_owned()).scribe(), Cow::Owned::<'static, str>("owasp.org".to_owned())); +//! assert_eq!(Website::Other("owasp.org".to_owned()).scribe(), +//! Cow::Owned::<'static, str>("owasp.org".to_owned())); //! ``` //! //! If you need to, you can use `#[enumscribe(ignore)]` to prevent a variant from being used by @@ -133,9 +137,11 @@ //! //! let flight_json = r#"{"takeoff":"LHR","landing":"LGW"}"#; //! -//! assert_eq!(serde_json::to_string(&flight).unwrap(), flight_json.to_owned()); +//! assert_eq!(serde_json::to_string(&flight).unwrap(), +//! flight_json.to_owned()); //! -//! assert_eq!(serde_json::from_str::(flight_json).unwrap(), flight); +//! assert_eq!(serde_json::from_str::(flight_json).unwrap(), +//! flight); //! ``` //! //! Here is a table to show which traits you should derive for your enum: @@ -179,7 +185,7 @@ pub trait ScribeStaticStr { /// Trait for converting an enum to a static string slice, or `None` if the conversion fails. /// /// Like all of the traits provided by enumscribe, this should not be implemented manually; use -/// `#[derive(ScribeStaticStr)]` provided by the [enumscribe_derive] crate instead. +/// `#[derive(TryScribeStaticStr)]` provided by the [enumscribe_derive] crate instead. /// /// When deriving this trait, you may specify the string that a particular variant should be /// converted to by annotating it with `#[enumscribe(str = "foo")]`. If this is omitted, the name @@ -198,7 +204,7 @@ pub trait TryScribeStaticStr { /// preferred over this trait because it avoids unnecessary allocations. /// /// Like all of the traits provided by enumscribe, this should not be implemented manually; use -/// `#[derive(ScribeStaticStr)]` provided by the [enumscribe_derive] crate instead. +/// `#[derive(ScribeString)]` provided by the [enumscribe_derive] crate instead. /// /// This trait can only be used if none of the enum's variants use `ignore`. pub trait ScribeString { @@ -210,7 +216,7 @@ pub trait ScribeString { /// allocations. /// /// Like all of the traits provided by enumscribe, this should not be implemented manually; use -/// `#[derive(ScribeStaticStr)]` provided by the [enumscribe_derive] crate instead. +/// `#[derive(TryScribeString)]` provided by the [enumscribe_derive] crate instead. pub trait TryScribeString { fn try_scribe(&self) -> Option; } @@ -218,7 +224,7 @@ pub trait TryScribeString { /// Trait for converting an enum to a clone-on-write string. /// /// Like all of the traits provided by enumscribe, this should not be implemented manually; use -/// `#[derive(ScribeStaticStr)]` provided by the [enumscribe_derive] crate instead. +/// `#[derive(ScribeCowStr)]` provided by the [enumscribe_derive] crate instead. /// /// When deriving this trait, you may specify the string that a particular variant should be /// converted to by annotating it with `#[enumscribe(str = "foo")]`. If this is omitted, the name @@ -234,10 +240,10 @@ pub trait ScribeCowStr { fn scribe(&self) -> Cow<'static, str>; } -// Trait for converting an enum to a clone-on-write string, or `None` if the conversion fails. +/// Trait for converting an enum to a clone-on-write string, or `None` if the conversion fails. /// /// Like all of the traits provided by enumscribe, this should not be implemented manually; use -/// `#[derive(ScribeStaticStr)]` provided by the [enumscribe_derive] crate instead. +/// `#[derive(TryScribeCowStr)]` provided by the [enumscribe_derive] crate instead. /// /// When deriving this trait, you may specify the string that a particular variant should be /// converted to by annotating it with `#[enumscribe(str = "foo")]`. If this is omitted, the name @@ -253,10 +259,35 @@ pub trait TryScribeCowStr { fn try_scribe(&self) -> Option>; } +/// Trait for converting from a string to an enum. +/// +/// Like all of the traits provided by enumscribe, this should not be implemented manually; use +/// `#[derive(Unscribe)]` provided by the [enumscribe_derive] crate instead. +/// +/// When deriving this trait, you may specify the string that should map to a particular variant +/// by annotating it with `#[enumscribe(str = "foo")]`. If this is omitted, the name of the variant +/// will be used instead. +/// +/// Annotating a variant with `#[enumscribe(case_insensitive)]` will cause case insensitive matching +/// to be used for that variant. If it is omitted, matching will be case sensitive. +/// +/// For this trait to be derived, there must be a variant marked with `#[enumscribe(other)]`. +/// If you do not have such a variant, try deriving [TryUnscribe] instead. pub trait Unscribe: Sized { fn unscribe(to_unscribe: &str) -> Self; } +/// Trait for converting from a string to an enum, or `None` if the conversion fails. +/// +/// Like all of the traits provided by enumscribe, this should not be implemented manually; use +/// `#[derive(TryUnscribe)]` provided by the [enumscribe_derive] crate instead. +/// +/// Annotating a variant with `#[enumscribe(case_insensitive)]` will cause case insensitive matching +/// to be used for that variant. If it is omitted, matching will be case sensitive. +/// +/// When deriving this trait, you may specify the string that should map to a particular variant +/// by annotating it with `#[enumscribe(str = "foo")]`. If this is omitted, the name of the variant +/// will be used instead. pub trait TryUnscribe: Sized { fn try_unscribe(to_unscribe: &str) -> Option; } diff --git a/enumscribe_derive/Cargo.toml b/enumscribe_derive/Cargo.toml index b546a6a..b8455da 100644 --- a/enumscribe_derive/Cargo.toml +++ b/enumscribe_derive/Cargo.toml @@ -5,6 +5,7 @@ authors = ["Tom Panton "] edition = "2018" license = "MIT" repository = "https://github.com/Pantonshire/enumscribe" +readme = "../README.md" description = "Procedural macros for converting between enums and strings" [lib] diff --git a/enumscribe_derive/src/lib.rs b/enumscribe_derive/src/lib.rs index e7be8b8..109caad 100644 --- a/enumscribe_derive/src/lib.rs +++ b/enumscribe_derive/src/lib.rs @@ -1,5 +1,6 @@ -//! Derive macros for the traits provided by enumscribe, to help you easily convert your enums -//! to strings and vice-versa. +//! Derive macros for the traits provided by `enumscribe`, to help you easily convert your enums +//! to strings and vice-versa. See the `enumscribe` crate's documentation for information on +//! deriving these traits. use proc_macro::TokenStream;