From e62d4a97aa8d0a5e5152c2ac1d785107bdf00fc1 Mon Sep 17 00:00:00 2001
From: Aaron Weiss <awe@pdgn.co>
Date: Wed, 24 Jan 2018 14:51:41 +0100
Subject: [PATCH] Added a first cut (without examples) of documentation for
 IrcReactor.

---
 src/client/reactor.rs | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/src/client/reactor.rs b/src/client/reactor.rs
index b255009..0d4847e 100644
--- a/src/client/reactor.rs
+++ b/src/client/reactor.rs
@@ -1,4 +1,4 @@
-//! A system for creating and managing multiple connections to IRC servers.
+//! A system for creating and managing IRC server connections.
 
 use futures::{Future, Stream};
 use futures::future;
@@ -15,6 +15,7 @@ pub struct IrcReactor {
 }
 
 impl IrcReactor {
+    /// Creates a new reactor.
     pub fn new() -> error::Result<IrcReactor> {
         Ok(IrcReactor {
             inner: Core::new()?,
@@ -22,18 +23,29 @@ impl IrcReactor {
         })
     }
 
+    /// Creates a representation of an IRC server that has not yet attempted to connect. In
+    /// particular, this representation is as a Future that when run will produce a connected
+    /// [IrcServer](./server/struct.IrcServer.html).
     pub fn prepare_server<'a>(&mut self, config: &'a Config) -> error::Result<IrcServerFuture<'a>> {
         IrcServer::new_future(self.inner.handle(), config)
     }
 
+    /// Runs an [IrcServerFuture](./server/struct.IrcServerFuture.html), such as one from
+    /// `prepare_server` to completion, yielding an [IrcServer](./server/struct.IrcServer.html).
     pub fn connect_server(&mut self, future: IrcServerFuture) -> error::Result<IrcServer> {
         self.inner.run(future)
     }
 
+    /// Creates a new IRC server from the specified configuration, connecting immediately. This is
+    /// guaranteed to be the composition of prepare_server and connect_server.
     pub fn prepare_server_and_connect(&mut self, config: &Config) -> error::Result<IrcServer> {
         self.prepare_server(config).and_then(|future| self.connect_server(future))
     }
 
+    /// Registers the given server with the specified message handler. The reactor will store this
+    /// setup until the next call to run, where it will be used to process new messages over the
+    /// connection indefinitely (or until failure). As registration is consumed by `run`, subsequent
+    /// calls to run will require new registration.
     pub fn register_server_with_handler<F>(
         &mut self, server: IrcServer, handler: F
     ) where F: Fn(&IrcServer, Message) -> error::Result<()> + 'static  {
@@ -42,12 +54,19 @@ impl IrcReactor {
         })));
     }
 
+    /// Registers an arbitrary future with this reactor. This is a sort of escape hatch that allows
+    /// you to take more control over what runs on the reactor without requiring you to bring in
+    /// additional knowledge about `tokio`. It is suspected that `register_server_with_handler` will
+    /// be sufficient for most use cases.
     pub fn register_future<F>(
         &mut self, future: F
     ) where F: Future<Item = (), Error = error::Error> + 'static {
         self.handlers.push(Box::new(future))
     }
 
+    /// Consumes all registered handlers and futures, and runs them. When using
+    /// `register_server_with_handler`, this will block indefinitely (until failure occurs) as it
+    /// will simply continue to process new, incoming messages for each server that was registered.
     pub fn run(&mut self) -> error::Result<()> {
         let mut handlers = Vec::new();
         while let Some(handler) = self.handlers.pop() {