Write docs for subscriptions and reorganize a bit

1 files changed, 61 insertions, 4 deletions

diff --git a/core/src/subscription.rs b/core/src/subscription.rs
index 21868c20..8de6cae8 100644
--- a/core/src/subscription.rs
+++ b/core/src/subscription.rs
@@ -1,6 +1,21 @@
-//! Generate events asynchronously for you application.
-
-/// An event subscription.
+//! Listen to external events in your application.
+
+/// A request to listen to external events.
+///
+/// Besides performing async actions on demand with [`Command`], most
+/// applications also need to listen to external events passively.
+///
+/// A [`Subscription`] is normally provided to some runtime, like a [`Command`],
+/// and it will generate events as long as the user keeps requesting it.
+///
+/// For instance, you can use a [`Subscription`] to listen to a WebSocket
+/// connection, keyboard presses, mouse events, time ticks, etc.
+///
+/// This type is normally aliased by runtimes with a specific `Input` and/or
+/// `Hasher`.
+///
+/// [`Command`]: ../struct.Command.html
+/// [`Subscription`]: struct.Subscription.html
 pub struct Subscription<Hasher, Input, Output> {
     recipes: Vec<Box<dyn Recipe<Hasher, Input, Output = Output>>>,
 }
@@ -9,12 +24,19 @@ impl<H, I, O> Subscription<H, I, O>
 where
     H: std::hash::Hasher,
 {
+    /// Returns an empty [`Subscription`] that will not produce any output.
+    ///
+    /// [`Subscription`]: struct.Subscription.html
     pub fn none() -> Self {
         Self {
             recipes: Vec::new(),
         }
     }
 
+    /// Creates a [`Subscription`] from a [`Recipe`] describing it.
+    ///
+    /// [`Subscription`]: struct.Subscription.html
+    /// [`Recipe`]: trait.Recipe.html
     pub fn from_recipe(
         recipe: impl Recipe<H, I, Output = O> + 'static,
     ) -> Self {
@@ -23,6 +45,10 @@ where
         }
     }
 
+    /// Batches all the provided subscriptions and returns the resulting
+    /// [`Subscription`].
+    ///
+    /// [`Subscription`]: struct.Subscription.html
     pub fn batch(
         subscriptions: impl Iterator<Item = Subscription<H, I, O>>,
     ) -> Self {
@@ -33,10 +59,16 @@ where
         }
     }
 
+    /// Returns the different recipes of the [`Subscription`].
+    ///
+    /// [`Subscription`]: struct.Subscription.html
     pub fn recipes(self) -> Vec<Box<dyn Recipe<H, I, Output = O>>> {
         self.recipes
     }
 
+    /// Transforms the [`Subscription`] output with the given function.
+    ///
+    /// [`Subscription`]: struct.Subscription.html
     pub fn map<A>(
         mut self,
         f: impl Fn(O) -> A + Send + Sync + 'static,
@@ -68,12 +100,37 @@ impl<I, O, H> std::fmt::Debug for Subscription<I, O, H> {
     }
 }
 
-/// The connection of an event subscription.
+/// The description of a [`Subscription`].
+///
+/// A [`Recipe`] is the internal definition of a [`Subscription`]. It is used
+/// by runtimes to run and identify subscriptions. You can use it to create your
+/// own!
+///
+/// [`Subscription`]: struct.Subscription.html
+/// [`Recipe`]: trait.Recipe.html
 pub trait Recipe<Hasher: std::hash::Hasher, Input> {
+    /// The events that will be produced by a [`Subscription`] with this
+    /// [`Recipe`].
+    ///
+    /// [`Subscription`]: struct.Subscription.html
+    /// [`Recipe`]: trait.Recipe.html
     type Output;
 
+    /// Hashes the [`Recipe`].
+    ///
+    /// This is used by runtimes to uniquely identify a [`Subscription`].
+    ///
+    /// [`Subscription`]: struct.Subscription.html
+    /// [`Recipe`]: trait.Recipe.html
     fn hash(&self, state: &mut Hasher);
 
+    /// Executes the [`Recipe`] and produces the stream of events of its
+    /// [`Subscription`].
+    ///
+    /// It receives some generic `Input`, which is normally defined by runtimes.
+    ///
+    /// [`Subscription`]: struct.Subscription.html
+    /// [`Recipe`]: trait.Recipe.html
     fn stream(
         self: Box<Self>,
         input: Input,