Add doctests and spawn method examples

examples/root_spv.rs

@@ -8,9 +8,9 @@ fn main() {
     Bastion::spawn(
         |context: BastionContext, msg: Box<dyn Message>| {
             // Message can be used here.
-            match Receive::<String>::from(msg) {
-                Receive(Some(o)) => println!("Received {}", o),
-                _ => println!("other message type..."),
+            receive! { msg,
+                String => |o| { println!("Received {}", o) },
+                _ => println!("other message type...")
             }
 
             println!("root supervisor - spawn_at_root - 1");

src/bastion.rs

@@ -290,7 +290,43 @@ impl Bastion {
         Bastion::unstable_shutdown()
     }
 
-
+    ///
+    /// Root supervisor's process spawner.
+    ///
+    /// If you don't need a supervision strategy other than [SupervisionStrategy::OneForOne], or
+    /// if your system doesn't need complex supervision. This is for you.
+    ///
+    /// This method helps you to get going with the basics.
+    ///
+    /// # Example
+    /// ```rust
+    ///    use bastion::prelude::*;
+    ///
+    ///    fn main() {
+    ///        Bastion::platform();
+    ///
+    ///        let message = String::from("Some message to be passed");
+    ///
+    ///        Bastion::spawn(
+    ///            |context: BastionContext, msg: Box<dyn Message>| {
+    ///                // Message can be used here.
+    ///                receive! { msg,
+    ///                    String => |o| { println!("Received {}", o) },
+    ///                    _ => println!("other message type...")
+    ///                }
+    ///
+    ///                println!("root supervisor - spawn_at_root - 1");
+    ///
+    ///                // Rebind to the system
+    ///                context.hook();
+    ///            },
+    ///            message,
+    ///        );
+    ///
+    ///        // Comment out to start the system, so runtime can initialize.
+    ///        // Bastion::start()
+    ///    }
+    /// ```
     pub fn spawn<F, M>(thunk: F, msg: M) -> BastionChildren
     where
         F: BastionClosure,

src/context.rs

@@ -1,3 +1,11 @@
+//!
+//! Context is generic structure to share resource between supervisor, children and the system.
+//!
+//! This enable us to work easily with system messages, api exposure and communication between processes.
+//!
+//! BastionContext is the main primitive to share this data anything related to internal
+//! communication is here.
+
 use crate::child::{BastionChildren, BastionClosure, Message};
 use crate::messages::PoisonPill;
 use crate::spawn::RuntimeSpawn;
@@ -16,6 +24,7 @@ use uuid::Uuid;
 
 ///
 /// Context definition for any lightweight process.
+///
 /// You can use context to:
 /// * spawn children
 /// * communicate with other spawned processes
@@ -95,6 +104,9 @@ impl BastionContext {
     /// you want to reutilize the process later and handover the control
     /// back again to the system after successful completion.
     ///
+    /// This function is a must to use for receiving signals from supervision and
+    /// applying supervision strategies.
+    ///
     /// # Examples
     /// ```
     /// use bastion::prelude::*;

src/supervisor.rs

@@ -7,6 +7,9 @@ use tokio::prelude::future::FutureResult;
 use tokio::prelude::*;
 use uuid::Uuid;
 
+///
+/// Identifier struct for Supervisor
+/// System uses this to assemble resource name for children and supervisors.
 #[derive(Clone, PartialOrd, PartialEq, Eq, Debug)]
 pub struct SupervisorURN {
     pub sys: String,  // Supervisor System Name
@@ -34,10 +37,33 @@ impl Ord for SupervisorURN {
     }
 }
 
+///
+/// Possible supervision strategies to pass to the supervisor.
+///
+/// **OneForOne**: If a child gets killed only that child will be restarted under the supervisor.
+///
+/// **OneForAll**: If a child gets killed all children at the same level under the supervision will be restarted.
+///
+/// **RestForOne**: If a child gets killed restart the rest of the children at the same level under the supervisor.
 #[derive(Clone, Debug)]
 pub enum SupervisionStrategy {
+    /// If a child gets killed only that child will be restarted under the supervisor.
+    ///
+    /// Example is from [learnyousomeerlang.com](https://learnyousomeerlang.com):
+    ///
+    /// ![](https://learnyousomeerlang.com/static/img/restart-one-for-one.png)
     OneForOne,
+    /// If a child gets killed all children at the same level under the supervision will be restarted.
+    ///
+    /// Example is from [learnyousomeerlang.com](https://learnyousomeerlang.com):
+    ///
+    /// ![](https://learnyousomeerlang.com/static/img/restart-one-for-all.png)
     OneForAll,
+    /// If a child gets killed restart the rest of the children at the same level under the supervisor.
+    ///
+    /// Example is from [learnyousomeerlang.com](https://learnyousomeerlang.com):
+    ///
+    /// ![](https://learnyousomeerlang.com/static/img/restart-rest-for-one.png)
     RestForOne,
 }
 

src/tramp.rs

@@ -1,8 +1,14 @@
+///
+/// Basic trampoline code for doing debouncing for supervision restarts.
+///
 pub enum Tramp<R> {
     Traverse(R),
     Complete(R),
 }
 
+///
+/// Execution implementation for the debouncer
+///
 impl<R> Tramp<R> {
     pub fn execute<F>(mut self, f: F) -> R
     where