Repository: cksac/fake-rs (language: rust)

Issue:
Add docs to docs.rs
It may be useful to duplicate the examples from README to docs.rs/fake (fake lib.rs).

I tried looking at the docs in https://docs.rs/fake/2.4.0/fake/ but I don't seemed to see any examples there, but I found it in the README. Adding it to the top-level library docs allows the users to read the docs offline which could not be done with README.


Discussion / hints:

Fix patch:
diff --git a/fake/Cargo.toml b/fake/Cargo.toml
index df0d4c4..4a57340 100644
--- a/fake/Cargo.toml
+++ b/fake/Cargo.toml
@@ -16,6 +16,9 @@ rand = "0.8"
 chrono = { version = "0.4", optional = true }
 http = { version = "0.2", optional = true }
 
+[dev-dependencies]
+fake = { path = ".", features = ["derive"] }
+
 [features]
 # Provide derive(Dummy) macros.
 derive = ["dummy"]
@@ -33,4 +36,4 @@ required-features = ["derive", "http", "chrono"]
 [[example]]
 name = "usage"
 path = "examples/usage.rs"
-required-features = ["derive"]
\ No newline at end of file
+required-features = ["derive"]
diff --git a/fake/examples/basic.rs b/fake/examples/basic.rs
index c1688d8..96d56dc 100644
--- a/fake/examples/basic.rs
+++ b/fake/examples/basic.rs
@@ -40,7 +40,7 @@ fn main() {
     // array
     let array: [u8; 0] = Faker.fake();
     println!("array {:?}", array);
-    let array: [u8; 3] = Faker.fake();
+    let array: [u8; 3] = (..10).fake();
     println!("array {:?}", array);
     let array: [[u8; 2]; 3] = (1..10).fake();
     println!("nested array {:?}", array);
diff --git a/fake/src/impls/std/collections/vec.rs b/fake/src/impls/std/collections/vec.rs
index d5623a8..c56c00e 100644
--- a/fake/src/impls/std/collections/vec.rs
+++ b/fake/src/impls/std/collections/vec.rs
@@ -31,6 +31,17 @@ where
     }
 }
 
+/// Creates a vec with fake values.
+///
+/// Requires `T: Dummy<Faker>` implementation for given type.
+///
+/// # Examples
+///
+/// ```
+/// let a = fake::vec![u8; 4]; // random u8 of length 4
+/// let b = fake::vec![u8; 4..8]; // random u8 of length 4 to 8
+/// // let c = fake::vec![u8; 4..]; // this won't work
+/// ```
 #[macro_export]
 macro_rules! vec {
     // @ty resolve type
diff --git a/fake/src/impls/std/path.rs b/fake/src/impls/std/path.rs
index 3d1649b..123d653 100644
--- a/fake/src/impls/std/path.rs
+++ b/fake/src/impls/std/path.rs
@@ -18,6 +18,10 @@ impl Dummy<Faker> for PathBuf {
     }
 }
 
+/// Custom fake path generator given an array of root directories, segments and
+/// extension, and max_level to generate a fake path.
+///
+/// It generates by `root_dirs / max_level * segments . extensions`.
 pub struct PathFaker<'a> {
     root_dirs: &'a [&'a str],
     segments: &'a [&'a str],
diff --git a/fake/src/impls/std/result.rs b/fake/src/impls/std/result.rs
index 91465c6..a48b6a7 100644
--- a/fake/src/impls/std/result.rs
+++ b/fake/src/impls/std/result.rs
@@ -15,6 +15,24 @@ where
     }
 }
 
+/// Custom fake [`Result`] generator.
+///
+/// # Examples
+///
+/// ```
+/// use fake::{Fake, ResultFaker};
+/// use fake::faker::name::en::Name;
+///
+/// // generate name on success but some error code on failure
+/// let f = ResultFaker::ok(Name());
+/// for _ in 0..2 {
+///     let a = f.fake::<Result<String, u8>>();
+/// }
+/// let f = ResultFaker::with(3.., 1..10);
+/// for _ in 0..5 {
+///     let a = f.fake::<Result<u32, usize>>();
+/// }
+/// ```
 pub struct ResultFaker<T, E> {
     ok: T,
     err: E,
diff --git a/fake/src/impls/std/string.rs b/fake/src/impls/std/string.rs
index e3f686f..9e85792 100644
--- a/fake/src/impls/std/string.rs
+++ b/fake/src/impls/std/string.rs
@@ -64,6 +64,19 @@ impl Dummy<ops::RangeToInclusive<usize>> for String {
     }
 }
 
+/// Custom fake [`String`] generator.
+///
+/// # Examples
+///
+/// ```
+/// use fake::{Fake, StringFaker};
+/// use fake::faker::name::en::Name;
+///
+/// // weak password generator
+/// const ASCII: &str = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!\"#$%&\'()*+,-./:;<=>?@";
+/// let f = StringFaker::with(Vec::from(ASCII), 8..12);
+/// let a: String = f.fake();
+/// ```
 pub struct StringFaker<L> {
     charset: Vec<u8>,
     len: L,
diff --git a/fake/src/lib.rs b/fake/src/lib.rs
index 149e184..2951130 100644
--- a/fake/src/lib.rs
+++ b/fake/src/lib.rs
@@ -1,13 +1,140 @@
+//! A library for generating fake data.
+//!
+//! # Feature flags
+//!
+//! - `derive` provides `#[derive(Dummy)]`
+//! - `chrono` [chrono](https://docs.rs/chrono) integration
+//! - `http` [http](https://docs.rs/http) integration
+//!
+//! # Usage
+//!
+//! ```
+//! use fake::{Dummy, Fake, Faker};
+//! use rand::rngs::StdRng;
+//! use rand::SeedableRng;
+//!
+//! #[derive(Debug, Dummy)]
+//! pub struct Foo {
+//!     #[dummy(faker = "1000..2000")]
+//!     order_id: usize,
+//!     customer: String,
+//!     paid: bool,
+//! }
+//!
+//! fn main() {
+//!     // type derived Dummy
+//!     let f: Foo = Faker.fake();
+//!     println!("{:?}", f);
+//!
+//!     // using `Faker` to generate default fake value of given type
+//!     let tuple = Faker.fake::<(u8, u32, f32)>();
+//!     println!("tuple {:?}", tuple);
+//!     println!("String {:?}", Faker.fake::<String>());
+//!
+//!     // types U can used to generate fake value T, if `T: Dummy<U>`
+//!     println!("String {:?}", (8..20).fake::<String>());
+//!     println!("u32 {:?}", (8..20).fake::<u32>());
+//!
+//!     // using `faker` module with locales
+//!     use fake::faker::name::raw::*;
+//!     use fake::locales::*;
+//!
+//!     let name: String = Name(EN).fake();
+//!     println!("name {:?}", name);
+//!
+//!     let name: String = Name(ZH_TW).fake();
+//!     println!("name {:?}", name);
+//!
+//!     // using convenient function without providing locale
+//!     use fake::faker::lorem::en::*;
+//!     let words: Vec<String> = Words(3..5).fake();
+//!     println!("words {:?}", words);
+//!
+//!     // using macro to generate nested collection
+//!     let name_vec = fake::vec![String as Name(EN); 4, 3..5, 2];
+//!     println!("random nested vec {:?}", name_vec);
+//!
+//!     // fixed seed rng
+//!     let seed = [
+//!         1, 0, 0, 0, 23, 0, 0, 0, 200, 1, 0, 0, 210, 30, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
+//!         0, 0, 0, 0,
+//!     ];
+//!     let ref mut r = StdRng::from_seed(seed);
+//!     for _ in 0..5 {
+//!         let v: usize = Faker.fake_with_rng(r);
+//!         println!("value from fixed seed {}", v);
+//!     }
+//! }
+//! ```
 use rand::Rng;
 
+/// Generate default fake value for given type using [`Fake`].
+///
+/// # Examples
+///
+/// ```
+/// use fake::{Fake, Faker};
+///
+/// let a: Option<usize> = Faker.fake();
+/// // or use turbofish syntax
+/// let b = Faker.fake::<Result<u32, u8>>();
+/// let c: (u8, u32, f32) = Faker.fake();
+/// // can also be combined with other values that implements Fake
+/// let d: (u8, u32, f32) = (1..10, Faker, 2.5..5.5).fake();
+/// let e: [u8; 3] = Faker.fake();
+/// let f: String = Faker.fake();
+/// // it also works for smart pointers and wrappers
+/// let g: std::pin::Pin<String> = Faker.fake();
+/// let h: Box<std::rc::Rc<u8>> = Faker.fake();
+/// let i: std::path::PathBuf = Faker.fake();
+/// ```
 pub struct Faker;
 
+/// Provide data structure a way to generate fake values.
+/// The opposite of [`Fake`].
+///
+/// [`Faker`] can be used as a generic `T` for `Dummy<T>` to generate a
+/// default fake value.
+///
+/// [`Dummy`] is similar to [`From`] trait, while [`Fake`] is similar to
+/// [`Into`] trait. Except in this case [`Fake`] cannot be implemented.
+///
+/// # Examples
+///
+/// ```
+/// use fake::{Dummy, Fake, Faker};
+/// use rand::Rng;
+/// use rand::seq::SliceRandom;
+///
+/// struct Name; // does not handle locale, see locales module for more
+///
+/// impl Dummy<Name> for &'static str {
+///     fn dummy_with_rng<R: Rng + ?Sized>(_: &Name, rng: &mut R) -> &'static str {
+///         const NAMES: &[&str] = &["John Doe", "Jane Doe"];
+///         NAMES.choose(rng).unwrap()
+///     }
+/// }
+///
+/// let name: &str = Name.fake();
+/// assert!(name == "John Doe" || name == "Jane Doe");
+/// ```
+///
+/// # Derivable
+///
+/// The trait can be used with `#[derive]` if all of the type's fields
+/// implement [`Fake`]. See [`Dummy`][macro@Dummy] for more.
 pub trait Dummy<T>: Sized {
+    /// Generate a dummy value for a type.
+    ///
+    /// This can be left as a blanket implemented most of the time since it
+    /// uses [`Dummy::dummy_with_rng`] under the hood.
     fn dummy(config: &T) -> Self {
         let mut r = rand::thread_rng();
         Dummy::<T>::dummy_with_rng(config, &mut r)
     }
 
+	/// Generate a dummy value for a given type using a random number
+	/// generator.
     fn dummy_with_rng<R: Rng + ?Sized>(config: &T, rng: &mut R) -> Self;
 }
 
@@ -31,6 +158,28 @@ mod private {
     }
 }
 
+/// Generate fake values given a type that implements [`Dummy`].
+/// The opposite of [`Dummy`].
+///
+/// Generate default fake values with [`Faker`].
+/// Generate specific fake values with helpers in [`faker`].
+///
+/// This trait is implemented for any type that implements [`Dummy`]:
+/// [`Dummy`] should be implemented instead, and you get the [`Fake`]
+/// implementation for free.
+///
+/// [`Dummy`] is similar to [`From`] trait, while [`Fake`] is similar to
+/// [`Into`] trait. Except in this case [`Fake`] cannot be implemented.
+///
+/// # Examples
+///
+/// ```
+/// use fake::Fake;
+///
+/// assert_eq!(10.fake::<String>().len(), 10);
+/// let a: [[u8; 2]; 3] = (1..10).fake();
+/// let b: Option<Option<usize>> = (1..10).fake();
+/// ```
 pub trait Fake: Sized {
     #[inline]
     fn fake<U>(&self) -> U
@@ -56,8 +205,51 @@ pub use impls::std::path::PathFaker;
 pub use impls::std::result::ResultFaker;
 pub use impls::std::string::StringFaker;
 
+/// Fake value generation for specific formats.
+///
+/// It is structured in a way such that the modules here describes the custom
+/// group for structs implemting [`Dummy`] to generate custom fake formats.
+///
+/// Within the module, there is multiple modules. With `raw` module providing
+/// a generic faker requiring a locale ([`faker::lorem::raw::Paragraph<L>`])
+/// and the rest of the modules providing a localized faker
+/// ([`faker::lorem::en::Paragraph`]) as convenient functions.
+///
+/// # Examples
+///
+/// ```
+/// use fake::Fake;
+/// use fake::faker::lorem::en::*;
+///
+/// let words: Vec<String> = Words(3..5).fake();
+/// ```
 pub mod faker;
+/// Localized data for [`faker`]. May be incomplete.
+///
+/// Locales used for custom [`Dummy`] implementations within [`faker`] module.
 pub mod locales;
 
+/// Derive macro generating an impl of the trait [`Dummy`].
+///
+/// # Examples
+///
+/// ```
+/// use fake::{Dummy, Fake, Faker};
+/// use fake::faker::name::en::Name;
+///
+/// #[derive(Dummy)]
+/// pub struct Foo {
+///     #[dummy(faker = "1000..2000")]
+///     order_id: usize,
+///     #[dummy(faker = "Name()")]
+///     customer: String,
+///     paid: bool,
+/// }
+///
+/// let f: Foo = Faker.fake();
+/// ```
+///
+/// `faker` key in `dummy` attribute could be used on any type that implements
+/// [`Fake`].
 #[cfg(feature = "derive")]
 pub use dummy::Dummy;


Test patch: