Cleanup and documentation

enumscribe/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "enumscribe"
-version = "0.1.0"
+version = "0.1.1"
 authors = ["Tom Panton <pantonshire@gmail.com>"]
 edition = "2018"
 license = "MIT"
@@ -11,7 +11,7 @@ categories = ["encoding"]
 keywords = ["enum", "derive", "serde"]
 
 [dependencies]
-enumscribe_derive = { version = "0.1.0", path = "../enumscribe_derive", optional = true }
+enumscribe_derive = { version = "0.1.0", path = "../enumscribe_derive", default-features = false, optional = true }
 
 [dev-dependencies]
 serde = { version = "1.0", features = ["derive"] }

enumscribe/README.md

@@ -2,11 +2,27 @@
 
 [![Build Status](https://travis-ci.com/Pantonshire/enumscribe.svg?branch=main)](https://travis-ci.com/Pantonshire/enumscribe)
 
-This crate provides derive macros for converting between simple enums and strings. It also includes derive macros for [`serde::Serialize`](https://docs.serde.rs/serde/trait.Serialize.html) and [`serde::Deserialize`](https://docs.serde.rs/serde/trait.Deserialize.html) for simple enums.
+This crate provides derive macros for converting between simple enums and strings. It also includes derive macros for
+[`serde::Serialize`](https://docs.serde.rs/serde/trait.Serialize.html) and
+[`serde::Deserialize`](https://docs.serde.rs/serde/trait.Deserialize.html) for simple enums.
+
+## Adding enumscribe to your project
+Add to your Cargo.toml file:
+
+```toml
+[dependencies]
+enumscribe = "0.1"
+```
+
+Derive macros and [`serde`](https://crates.io/crates/serde) support are enabled by default. They can be disabled by
+setting `default-features = false`.
+
+It is also possible to use the `enumscribe_derive` crate on its own without using the `enumscribe` crate. However,
+doing so means that you will only be able to derive `serde::Serialize` and `serde::Deserialize`.
 
 ## Usage
-There are a variety of different traits that you can derive. The "Scribe" traits are for converting from an enum to a string, and the "Unscribe" traits are for
-converting a string to an enum.
+There are a variety of different traits that you can derive. The "Scribe" traits are for converting from an enum to a
+string, and the "Unscribe" traits are for converting a string to an enum.
 
 ### Basic usage
 ```rust
@@ -29,11 +45,12 @@ assert_eq!(Airport::Heathrow.scribe(), "LHR");
 assert_eq!(Airport::try_unscribe("LGW"), Some(Airport::Gatwick));
 ```
 
-The `#[enumscribe(str = "...")]` allows us to specify what string should be used to represent a particular variant. If this is omitted, the name of the variant
-will be used instead.
+The `#[enumscribe(str = "...")]` allows us to specify what string should be used to represent a particular variant. If
+this is omitted, the name of the variant will be used instead.
 
 ### Case insensitivity
-The `#[enumscribe(case_insensitive)]` attribute can be used to make the "Unscribe" traits perform case-insensitive matching for a variant:
+The `#[enumscribe(case_insensitive)]` attribute can be used to make the "Unscribe" traits perform case-insensitive
+matching for a variant:
 
 ```rust
 use enumscribe::TryUnscribe;
@@ -50,8 +67,8 @@ assert_eq!(Website::try_unscribe("GiThUb.CoM"), Some(Website::Github));
 ```
 
 ### "other" variant
-You can also have a variant which stores strings that could not be matched to any other variant. This is done using the `#[enumscribe(other)]` attribute.
-The variant should have a single field, which is a `String`.
+You can also have a variant which stores strings that could not be matched to any other variant. This is done using the
+`#[enumscribe(other)]` attribute. The variant should have a single field, which is a `String`.
 
 ```rust
 use std::borrow::Cow;

enumscribe/src/lib.rs

@@ -162,6 +162,8 @@
 //! Therefore, you should prefer the `ScribeCowStr` traits over the `ScribeString` traits, unless
 //! you *really* don't want to use a `Cow` for whatever reason.
 
+#![deny(missing_docs)]
+
 #[macro_use]
 extern crate enumscribe_derive;
 
@@ -200,6 +202,11 @@ use std::borrow::Cow;
 /// assert_eq!(Airport::UnnamedAirport.scribe(), "UnnamedAirport");
 /// ```
 pub trait ScribeStaticStr {
+    /// Converts this enum to a `&'static str`.
+    ///
+    /// The string returned for a particular variant is determined by the
+    /// `#[enumscribe(str = "...")]` attribute, or the name of the variant if the attribute
+    /// is omitted.
     fn scribe(&self) -> &'static str;
 }
 
@@ -236,6 +243,11 @@ pub trait ScribeStaticStr {
 /// assert_eq!(Airport::UnnamedAirport.try_scribe(), Some("UnnamedAirport"));
 /// ```
 pub trait TryScribeStaticStr {
+    /// Converts this enum to a `Option<&'static str>`.
+    ///
+    /// Calling this method on a variant marked with `#[enumscribe(ignore)]` will return `None`.
+    /// Calling it on any other variant will return `Some("...")`, where `"..."` is the string
+    /// specified by the `#[enumscribe(str = "...")]` attribute.
     fn try_scribe(&self) -> Option<&'static str>;
 }
 
@@ -266,6 +278,12 @@ pub trait TryScribeStaticStr {
 /// assert_eq!(Airport::Other("STN".to_owned()).scribe(), "STN".to_owned());
 /// ```
 pub trait ScribeString {
+    /// Converts this enum to an allocated `String`.
+    ///
+    /// When called on a variant marked with `#[enumscribe(other)]`, the variant's field will be
+    /// returned. For other variants, the string returned is determined by the
+    /// `#[enumscribe(str = "...")]` attribute, or the name of the variant if the attribute is
+    /// omitted.
     fn scribe(&self) -> String;
 }
 
@@ -295,6 +313,14 @@ pub trait ScribeString {
 /// assert_eq!(Airport::Other("STN".to_owned()).try_scribe(), Some("STN".to_owned()));
 /// ```
 pub trait TryScribeString {
+    /// Converts this enum to an allocated `String`.
+    ///
+    /// Calling this method on a variant marked with `#[enumscribe(ignore)]` will return `None`.
+    ///
+    /// When called on a variant marked with `#[enumscribe(other)]`, the variant's field will be
+    /// returned. For other variants, the string returned is determined by the
+    /// `#[enumscribe(str = "...")]` attribute, or the name of the variant if the attribute is
+    /// omitted.
     fn try_scribe(&self) -> Option<String>;
 }
 
@@ -338,6 +364,12 @@ pub trait TryScribeString {
 ///            Cow::Owned::<'static, str>("STN".to_owned()));
 /// ```
 pub trait ScribeCowStr {
+    /// Converts this enum to a `Cow<'static, str>`.
+    ///
+    /// When called on a variant marked with `#[enumscribe(other)]`, the variant's field will be
+    /// returned as a `Cow::Owned`. For other variants, a `Cow::Borrowed` is returned, containing
+    /// a static string slice determined by the `#[enumscribe(str = "...")]` attribute, or the name
+    /// of the variant if the attribute is omitted.
     fn scribe(&self) -> Cow<'static, str>;
 }
 
@@ -381,6 +413,14 @@ pub trait ScribeCowStr {
 ///            Some(Cow::Owned::<'static, str>("STN".to_owned())));
 /// ```
 pub trait TryScribeCowStr {
+    /// Converts this enum to a `Option<Cow<'static, str>>`.
+    ///
+    /// Calling this method on a variant marked with `#[enumscribe(ignore)]` will return `None`.
+    ///
+    /// When called on a variant marked with `#[enumscribe(other)]`, the variant's field will be
+    /// returned as a `Cow::Owned`. For other variants, a `Cow::Borrowed` is returned, containing
+    /// a static string slice determined by the `#[enumscribe(str = "...")]` attribute, or the name
+    /// of the variant if the attribute is omitted.
     fn try_scribe(&self) -> Option<Cow<'static, str>>;
 }
 
@@ -425,6 +465,11 @@ pub trait TryScribeCowStr {
 /// assert_eq!(Airport::unscribe("stn"), Airport::Other("stn".to_owned()));
 /// ```
 pub trait Unscribe: Sized {
+    /// Converts the given string to an enum variant.
+    ///
+    /// The given string is matched against the `#[enumscribe(str = "...")]` attribute for each
+    /// variant to determine which variant to return. If there was no successful match, the
+    /// variant marked with `#[enumscribe(other)]` will be returned instead.
     fn unscribe(to_unscribe: &str) -> Self;
 }
 
@@ -462,5 +507,12 @@ pub trait Unscribe: Sized {
 /// assert_eq!(Airport::try_unscribe("stn"), None);
 /// ```
 pub trait TryUnscribe: Sized {
+    /// Converts the given string to an enum variant, or `None` if the conversion was not
+    /// successful.
+    ///
+    /// The given string is matched against the `#[enumscribe(str = "...")]` attribute for each
+    /// variant to determine which variant to return. If there was no successful match, the
+    /// variant marked with `#[enumscribe(other)]` will be returned instead. If there is no
+    /// variant marked with `#[enumscribe(other)]`, then `None` will be returned.
     fn try_unscribe(to_unscribe: &str) -> Option<Self>;
 }