Added documentation for aktoro-raw.

Author: r3v2d0g

aktoro-raw/src/action.rs

@@ -13,5 +13,7 @@ pub trait Action: Send {
 pub trait ActionHandler<A: Send + 'static>: Actor {
     type Output: Send;
 
+    /// Handles the action, returning a result
+    /// eventually containing the action's output.
     fn handle(&mut self, action: A, ctx: &mut Self::Context) -> Result<Self::Output, Self::Error>;
 }

aktoro-raw/src/actor.rs

@@ -10,23 +10,60 @@ pub trait Actor: Unpin + Send + Sized + 'static {
     type Error: StdError + Send;
 
     #[allow(unused)]
+    /// Called when the actor's context has been created
+    /// but it hasn't been spawned by the runtime yet.
     fn starting(&mut self, ctx: &mut Self::Context) {}
 
     #[allow(unused)]
+    /// Called when the actor's has been spawned by the
+    /// runtime and polled for the first time.
     fn started(&mut self, ctx: &mut Self::Context) {}
 
     #[allow(unused)]
+    /// Called when the actor has been asked to stop
+    /// but has been left the option to cancel it.
     fn stopping(&mut self, ctx: &mut Self::Context) {}
 
     #[allow(unused)]
+    /// Called when the actor has accepted to stop or
+    /// it has been asked to stop immediately.
     fn stopped(&mut self, ctx: &mut Self::Context) {}
 }
 
 pub trait Status: PartialEq + Default + Clone + Send {
+    /// Returns the status that an actor should have
+    /// before [`Actor::starting`] is called.
+    ///
+    /// [`Actor::starting`]: trait.Actor.html#method.starting
     fn starting() -> Self;
+
+    /// Returns the status that an actor should have
+    /// before [`Actor::started`] is called.
+    ///
+    /// [`Actor::started`]: trait.Actor.html#methood.started
     fn started() -> Self;
+
+    /// Returns the status that an actor should have
+    /// before [`Actor::stopping`] is called.
+    ///
+    /// ## Note
+    ///
+    /// If after [`Actor::stopping`] is called, its
+    /// status is still the same it will be stopped.
+    ///
+    /// [`Actor::stopping`]: trait.Actor.html#method.stopping
     fn stopping() -> Self;
+
+    /// Returns the status that an actor should have
+    /// before [`Actor::stopped`] is called.
+    ///
+    /// [`Actor::stopped`]: trait.Actor.html#method.stopped
     fn stopped() -> Self;
+
+    /// Returns the status that an actor will have
+    /// after [`Actor::stopped`] has been called.
+    ///
+    /// [`Actor::stopped`]: trait.Actor.html#method.stopped
     fn dead() -> Self;
 
     fn is_starting(&self) -> bool;

aktoro-raw/src/channel.rs

@@ -7,13 +7,22 @@ use crate::actor::Actor;
 use crate::message::Handler;
 use crate::message::Message;
 
+/// The result returned by the [`Sender::try_send`]
+/// method.
+///
+/// `Ok` contains a future resolving with the result
+/// returned by the message handler.
+///
+/// [`Sender::try_send`]: trait.Sender.html#method.try_send
 pub type SenderRes<'s, O, E> = Result<BoxFuture<'s, Result<O, E>>, E>;
 
 pub trait Sender<A: Actor>: Clone {
     type Receiver: Receiver<A>;
 
     type Error: StdError + Send;
 
+    /// Tries to send a message to be handled by the
+    /// actor.
     fn try_send<M>(&mut self, msg: M) -> SenderRes<A::Output, Self::Error>
     where
         A: Handler<M>,

aktoro-raw/src/context.rs

@@ -14,31 +14,69 @@ pub trait Context<A: Actor>: Unpin + Send + 'static + Stream<Item = Work<A>> {
     type Sender: Sender<A>;
     type Updater: Updater<A>;
 
+    /// Creates a new context for an actor.
     fn new() -> Self;
 
+    /// Emits an event that will be handled by the
+    /// actor.
     fn emit<E>(&mut self, event: E)
     where
         A: EventHandler<E>,
         E: Send + 'static;
 
+    /// Gets the actor's current status.
     fn status(&self) -> &A::Status;
+
+    /// Sets the actor's current status, eventually
+    /// making action to reflect the change (e.g. by
+    /// stopping the actor).
     fn set_status(&mut self, status: A::Status);
+
+    /// Shares the actor's current status through
+    /// the actor's update channel.
     fn update(&mut self) -> Result<(), <Self::Updater as Updater<A>>::Error>;
 
+    /// Gets the actor's action channel sender.
     fn controller(&self) -> &Self::Controller;
+
+    /// Gets the actor's message channel sender.
     fn sender(&self) -> &Self::Sender;
 
+    /// Tries to get a mutable reference to the
+    /// actor's update channel sender.
     fn updated_ref(&mut self) -> Option<&mut <Self::Updater as Updater<A>>::Updated>;
+
+    /// Tries to get the actor's update channel
+    /// sender.
     fn updated(&mut self) -> Option<<Self::Updater as Updater<A>>::Updated>;
 
+    /// Gets a mutable reference to the actor's
+    /// action channel receiver.
     fn controlled(&mut self) -> &mut <Self::Controller as Controller<A>>::Controlled;
+
+    /// Gets a mutable reference to the actor's
+    /// message channel receiver.
     fn receiver(&mut self) -> &mut <Self::Sender as Sender<A>>::Receiver;
+
+    /// Gets a mutable reference to the actors's
+    /// update channel receiver.
     fn updater(&mut self) -> &mut Self::Updater;
 }
 
 pub enum Work<A: Actor> {
+    /// Contains an action that should be handled
+    /// by the actor.
     Action(Box<dyn Action<Actor = A>>),
+
+    /// Contains an event that should be handled
+    /// by the actor.
     Event(Box<dyn Event<Actor = A>>),
+
+    /// Contains a message that should be handled
+    /// by the actor.
     Message(Box<dyn Message<Actor = A>>),
+
+    /// Indicates that the actor's status has
+    /// changed.
     Update,
 }

aktoro-raw/src/control.rs

@@ -7,13 +7,22 @@ use crate::action::Action;
 use crate::action::ActionHandler;
 use crate::actor::Actor;
 
+/// The result returned by the [`Controller::try_send`]
+/// method.
+///
+/// `Ok` contains a future resolving with the result
+/// returned by the action handler.
+///
+/// [`Controller::try_send`]: trait.Controller.html#method.try_send
 pub type ControllerRes<'c, O, E> = Result<BoxFuture<'c, Result<O, E>>, E>;
 
 pub trait Controller<A: Actor>: Clone {
     type Controlled: Controlled<A>;
 
     type Error: StdError + Send;
 
+    /// Tries to send an action to be handled by the
+    /// actor.
     fn try_send<D>(&mut self, action: D) -> ControllerRes<A::Output, Self::Error>
     where
         A: ActionHandler<D>,

aktoro-raw/src/event.rs

@@ -11,5 +11,6 @@ pub trait Event: Send {
 }
 
 pub trait EventHandler<E: Send + 'static>: Actor {
+    /// Handles the event.
     fn handle(&mut self, event: E, ctx: &mut Self::Context) -> Result<(), Self::Error>;
 }

aktoro-raw/src/message.rs

@@ -13,5 +13,7 @@ pub trait Message: Send {
 pub trait Handler<M: Send + 'static>: Actor {
     type Output: Send;
 
+    /// Handles the message, returning a result
+    /// eventually containing the message's output.
     fn handle(&mut self, msg: M, ctx: &mut Self::Context) -> Result<Self::Output, Self::Error>;
 }

aktoro-raw/src/runtime.rs

@@ -5,14 +5,39 @@ use crate::actor::Actor;
 use crate::spawned::Spawned;
 
 pub trait Runtime {
+    /// The future returned after calling the
+    /// [`stop`] method. It will resolve after
+    /// all the actors have been stopped.
+    ///
+    /// [`stop`]: #method.stop
     type Stop: Future<Output = Result<(), Self::Error>>;
+
+    /// The future returned after calling the
+    /// [`wait`] method. It will resolve after
+    /// all the actors have been stopped.
+    ///
+    /// [`wait`]: #method.wait
     type Wait: Future<Output = Result<(), Self::Error>>;
 
     type Error: StdError;
 
+    /// Spawns a new actor on the runtime,
+    /// returning [`Some(Spawned<A>)`] if it
+    /// succeeded or [`None`] if it failed or
+    /// if the actor stopped itself when
+    /// [`Actor::starting`] was called.
+    ///
+    /// [`Some(Spawned<A>)`]: sturct.Spawned.html
+    /// [`Actor::starting`]: trait.Actor.html#method.starting
     fn spawn<A: Actor>(&mut self, actor: A) -> Option<Spawned<A>>;
 
+    /// Asks to all the actors managed by the
+    /// runtime, to stop, returning a future
+    /// resolving after all of them have been
+    /// stopped.
     fn stop(self) -> Self::Stop;
 
+    /// Waits for all the actors to be stopped,
+    /// returning a future waiting for it.
     fn wait(self) -> Self::Wait;
 }

aktoro-raw/src/spawned.rs

@@ -29,6 +29,13 @@ pub struct Spawned<A: Actor> {
 }
 
 impl<A: Actor> Spawned<A> {
+    /// Creates a new `Spawned` struct from an actor's
+    /// context.
+    ///
+    /// ## Note
+    ///
+    /// This should only be used by a runtime after
+    /// an actor has finished starting.
     pub fn new(ctx: &mut A::Context) -> Spawned<A> {
         Spawned {
             sender: ctx.sender().clone(),
@@ -40,6 +47,10 @@ impl<A: Actor> Spawned<A> {
         }
     }
 
+    /// Tries to send a message over the actor's
+    /// message channel, returning a future
+    /// resolving with the result returned by the
+    /// message handler.
     pub fn try_send_msg<M>(&mut self, msg: M) -> SenderRes<A::Output, SenderError<A>>
     where
         A: Handler<M>,
@@ -48,6 +59,10 @@ impl<A: Actor> Spawned<A> {
         self.sender.try_send(msg)
     }
 
+    /// Tries send an action over the actor's
+    /// control channel, returning a future resolving
+    /// with the result returned by the action 
+    /// handler.
     pub fn try_send_action<D>(&mut self, action: D) -> ControllerRes<A::Output, ControllerError<A>>
     where
         A: ActionHandler<D>,
@@ -56,21 +71,29 @@ impl<A: Actor> Spawned<A> {
         self.ctrler.try_send(action)
     }
 
+    /// Returns a reference to the actor's message
+    /// channel sender.
     pub fn sender(&self) -> &Sender<A> {
         &self.sender
     }
 
+    /// Returns a reference to the actor's control
+    /// channel sender.
     pub fn controller(&self) -> &Controller<A> {
         &self.ctrler
     }
 
-    pub fn updated(&mut self) -> Option<Updated<A>> {
-        self.updted.take()
-    }
-
+    /// Tries to return a mutable reference to the
+    /// actor's update channel receiver.
     pub fn updated_ref(&mut self) -> Option<&mut Updated<A>> {
         self.updted.as_mut()
     }
+
+    /// Tries to return the actor's update channel
+    /// receiver.
+    pub fn updated(&mut self) -> Option<Updated<A>> {
+        self.updted.take()
+    }
 }
 
 impl<A: Actor> Unpin for Spawned<A> {}

aktoro-raw/src/update.rs

@@ -9,6 +9,8 @@ pub trait Updater<A: Actor> {
 
     type Error: StdError + Send;
 
+    /// Tries to send a status update over
+    /// the actor's update channel.
     fn try_send(&mut self, status: A::Status) -> Result<(), Self::Error>;
 }