From f14009601e270e43bdf29b8f4842cf136fbbd8b9 Mon Sep 17 00:00:00 2001
From: Héctor Ramón Jiménez <hector0193@gmail.com>
Date: Mon, 20 Jan 2020 09:49:17 +0100
Subject: Write documentation for `iced_futures`

---
 futures/src/runtime.rs | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

(limited to 'futures/src/runtime.rs')

diff --git a/futures/src/runtime.rs b/futures/src/runtime.rs
index a508c46e..9fd9899a 100644
--- a/futures/src/runtime.rs
+++ b/futures/src/runtime.rs
@@ -4,6 +4,15 @@ use crate::{subscription, Command, Executor, Subscription};
 use futures::Sink;
 use std::marker::PhantomData;
 
+/// A batteries-included runtime of commands and subscriptions.
+///
+/// If you have an [`Executor`], a [`Runtime`] can be leveraged to run any
+/// [`Command`] or [`Subscription`] and get notified of the results!
+///
+/// [`Runtime`]: struct.Runtime.html
+/// [`Executor`]: executor/trait.Executor.html
+/// [`Command`]: struct.Command.html
+/// [`Subscription`]: subscription/struct.Subscription.html
 #[derive(Debug)]
 pub struct Runtime<Hasher, Event, Executor, Sender, Message> {
     executor: Executor,
@@ -25,6 +34,13 @@ where
         + 'static,
     Message: Send + 'static,
 {
+    /// Creates a new empty [`Runtime`].
+    ///
+    /// You need to provide:
+    /// - an [`Executor`] to spawn futures
+    /// - a `Sender` implementing `Sink` to receive the results
+    ///
+    /// [`Runtime`]: struct.Runtime.html
     pub fn new(executor: Executor, sender: Sender) -> Self {
         Self {
             executor,
@@ -34,10 +50,24 @@ where
         }
     }
 
+    /// Runs the given closure inside the [`Executor`] of the [`Runtime`].
+    ///
+    /// See [`Executor::enter`] to learn more.
+    ///
+    /// [`Executor`]: executor/trait.Executor.html
+    /// [`Runtime`]: struct.Runtime.html
+    /// [`Executor::enter`]: executor/trait.Executor.html#method.enter
     pub fn enter<R>(&self, f: impl FnOnce() -> R) -> R {
         self.executor.enter(f)
     }
 
+    /// Spawns a [`Command`] in the [`Runtime`].
+    ///
+    /// The resulting `Message` will be forwarded to the `Sender` of the
+    /// [`Runtime`].
+    ///
+    /// [`Command`]: struct.Command.html
+    /// [`Runtime`]: struct.Runtime.html
     pub fn spawn(&mut self, command: Command<Message>) {
         use futures::{FutureExt, SinkExt};
 
@@ -56,6 +86,14 @@ where
         }
     }
 
+    /// Tracks a [`Subscription`] in the [`Runtime`].
+    ///
+    /// It will spawn new streams or close old ones as necessary! See
+    /// [`Tracker::update`] to learn more about this!
+    ///
+    /// [`Subscription`]: subscription/struct.Subscription.html
+    /// [`Runtime`]: struct.Runtime.html
+    /// [`Tracker::update`]: subscription/struct.Tracker.html#method.update
     pub fn track(
         &mut self,
         subscription: Subscription<Hasher, Event, Message>,
@@ -68,6 +106,13 @@ where
         }
     }
 
+    /// Broadcasts an event to all the subscriptions currently alive in the
+    /// [`Runtime`].
+    ///
+    /// See [`Tracker::broadcast`] to learn more.
+    ///
+    /// [`Runtime`]: struct.Runtime.html
+    /// [`Tracker::broadcast`]: subscription/struct.Tracker.html#method.broadcast
     pub fn broadcast(&mut self, event: Event) {
         self.subscriptions.broadcast(event);
     }
-- 
cgit