Adds a complete example, and some doctest/examples

README.md

@@ -1,3 +1,15 @@
-# Shard
+# Shared
 
 A Arc Mutex guarded Data.
+
+## Usage
+
+`cargo add shared`
+
+```rust
+use shared::Shared;
+```
+
+## Examples
+
+To run, say `doc_example` just `cargo run --example doc_example`.

examples/doc_example.rs

@@ -0,0 +1,37 @@
+use shared::Shared;
+
+#[derive(Clone)]
+struct Person {
+    pub name: String,
+    pub age: u16,
+}
+
+// Using it as a parameter
+async fn get_older(shared: Shared<Person>) {
+    let mut person = shared.lock().await;
+    person.age += 1;
+}
+
+#[tokio::main]
+async fn main() {
+    let shared_data = Shared::new(Person {
+        name: "Test Dummy".to_string(),
+        age: 30,
+    });
+
+    {
+        // Direct access
+        let person = shared_data.lock().await;
+        println!("Before:");
+        println!("Person{{name: {}, age: {}}}", person.name, person.age);
+    }
+
+    // Calling
+    get_older(shared_data.clone()).await;
+
+    {
+        let person = shared_data.lock().await;
+        println!("After:");
+        println!("Person{{name: {}, age: {}}}", person.name, person.age);
+    }
+}

src/lib.rs

@@ -11,6 +11,30 @@ pub struct Shared<T> {
 }
 
 impl<T> Shared<T> {
+    /// Creates a new Shared of data T
+    ///
+    /// > Want to see a complete example, look at doc_example in the examples directory
+    /// 
+    /// Example:
+    /// ```
+    /// use shared::Shared;
+    ///
+    /// #[derive(Clone)]
+    /// struct Person {
+    ///     pub name: String,
+    ///     pub age: u16
+    /// }
+    ///
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     let shared_data = Shared::new(Person{
+    ///         name: "Test Dummy".to_string(),
+    ///         age: 30
+    ///     });
+    ///
+    ///     // See Shared::lock for using it
+    /// }
+    /// ```
     pub fn new(data: T) -> Self {
         Shared {
             data: Arc::new(Mutex::new(data)),
@@ -18,75 +42,26 @@ impl<T> Shared<T> {
     }
 
     /// Acquire lock
+    /// 
+    /// > Want to see a complete example, look at doc_example in the examples directory
     ///
     /// Using:
     /// ```
-    /// use shared::Shared;
-    /// 
-    /// #[derive(Clone)]
-    /// struct Post {
-    ///     pub id: i32,
-    ///     pub title: String,
-    ///     pub author: String,
-    /// }
+    /// // See Shared::new for creating a Shared<Person>
     /// 
-    /// #[derive(Clone)]
-    /// struct ExampleData {
-    ///     pub name: String,
-    ///     pub age: u16,
-    ///     pub last_post: Shared<Post>
+    /// { // Direct access
+    ///     let person = shared_data.lock().await;
+    ///     println!("Person{{name: {}, age: {}}}", person.name, person.age);
     /// }
     /// 
-    /// async fn do_something(shared: Shared<ExampleData>) {
-    ///     let mut example = shared.lock().await;
-    ///     example.age += 1;
-    ///     {
-    ///         let mut post = example.last_post.lock().await;
-    ///         post.id += 1;
-    ///         post.title = "Sharing Data in Rust, It's Easy".to_string();
-    ///     }
+    /// // Using it as a parameter
+    /// async fn get_older(shared: Shared<Person>) {
+    ///     let mut person = shared.lock().await;
+    ///     person.age += 1;
     /// }
     /// 
-    /// #[tokio::main]
-    /// async fn main() {
-    ///     let ex_data = Shared::new(ExampleData{
-    ///         name: "Test Dummy".to_string(),
-    ///         age: 30,
-    ///         last_post: Shared::new(Post{
-    ///             id: 10,
-    ///             title: "Sharing Data in Rust, The Easy Way".to_string(),
-    ///             author: "Test Dummy".to_string(),
-    ///         })
-    ///     });
-    /// 
-    ///     {
-    ///         let example = ex_data.lock().await;
-    ///         println!("Before:");
-    ///         println!("name: {}", example.name);
-    ///         println!("age:  {}", example.age);
-    ///         {
-    ///             let post = example.last_post.lock().await;
-    ///             println!("last_post.id:     {}", post.id);
-    ///             println!("last_post.title:  {}", post.title);
-    ///             println!("last_post.author: {}", post.author);
-    ///         }
-    ///     }
-    /// 
-    ///     do_something(ex_data.clone()).await;
-    /// 
-    ///     {
-    ///         let example = ex_data.lock().await;
-    ///         println!("Before:");
-    ///         println!("name: {}", example.name);
-    ///         println!("age:  {}", example.age);
-    ///         {
-    ///             let post = example.last_post.lock().await;
-    ///             println!("last_post.id:     {}", post.id);
-    ///             println!("last_post.title:  {}", post.title);
-    ///             println!("last_post.author: {}", post.author);
-    ///         }
-    ///     }
-    /// }
+    /// // Calling
+    /// get_older(shared_data.clone()).await;
     /// ```
     pub async fn lock(&self) -> MutexGuard<'_, T> {
         let result = timeout(Duration::from_secs(LOCK_TIMEOUT), self.data.lock()).await;