From 000e7c4e4c2e5aca557503403e7e9cea8da5fc80 Mon Sep 17 00:00:00 2001
From: xd009642 <danielmckenna93@gmail.com>
Date: Tue, 15 Aug 2023 14:25:08 +0100
Subject: [PATCH] Improves the docs on derive

So I've done a bit of work to improve the derive docs.

I do think another improvement may be to copy the style
done in the tokio docs and for some simple examples
show how the generated code looks. However, I think fake would benefit
less from this compared to tokio (how a runtime is setup for an async
application is important to more people). So it may just add unnecessary
noise to the docs.

I guess an issue should be made for the tuple enums - or maybe there's
another way to do it I need to experiment/read-macro-code more
---
 fake/src/lib.rs | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/fake/src/lib.rs b/fake/src/lib.rs
index e16ef6f..9aa3ec9 100644
--- a/fake/src/lib.rs
+++ b/fake/src/lib.rs
@@ -271,10 +271,15 @@ pub mod faker;
 /// Locales used for custom [`Dummy`] implementations within [`faker`] module.
 pub mod locales;
 
-/// Derive macro generating an impl of the trait [`Dummy`].
+/// Derive macro generating an impl of the trait [`Dummy`]. This works for both structs and enums.
+///
+/// For any fields in the type the `faker` key in `dummy` attribute could be used provided the field
+/// implements [`Fake`].
 ///
 /// # Examples
 ///
+/// A simple example for deriving [`Dummy`] on a struct:
+///
 /// ```
 /// use fake::{Dummy, Fake, Faker};
 /// use fake::faker::name::en::Name;
@@ -291,8 +296,26 @@ pub mod locales;
 /// let f: Foo = Faker.fake();
 /// ```
 ///
-/// `faker` key in `dummy` attribute could be used on any type that implements
-/// [`Fake`].
+/// A simple example for deriving [`Dummy`] on an enum. Unfortunately, the `faker` key cannot yet
+/// be used on tuple enum variants. However, it can be used on fields within struct enum variants.
+///
+/// ```
+/// use fake::{Dummy, Fake, Faker};
+/// use fake::faker::name::en::Name;
+///
+/// #[derive(Dummy)]
+/// pub struct Bar {
+///     Simple,
+///     Tuple(i32),
+///     Structure {
+///         #[dummy(faker = "1000..2000")]
+///         i: usize,
+///         j: String,
+///     }
+/// }
+///
+/// let f: Foo = Faker.fake();
+/// ```
 #[cfg(feature = "derive")]
 pub use dummy::Dummy;