Document Handle::default() behavior (#359)

tokio-reactor/src/lib.rs

@@ -94,6 +94,9 @@ pub struct Reactor {
 /// A `Handle` is used for associating I/O objects with an event loop
 /// explicitly. Typically though you won't end up using a `Handle` that often
 /// and will instead use the default reactor for the execution context.
+///
+/// By default, most components bind lazily to reactors.
+/// To get this behavior when manually passing a `Handle`, use `default()`.
 #[derive(Clone)]
 pub struct Handle {
     inner: Option<HandlePriv>,
@@ -475,6 +478,7 @@ impl Unpark for Handle {
 }
 
 impl Default for Handle {
+    /// Returns a "default" handle, i.e., a handle that lazily binds to a reactor.
     fn default() -> Handle {
         Handle { inner: None }
     }

tokio-tcp/src/listener.rs

@@ -159,6 +159,7 @@ impl TcpListener {
     ///
     /// Finally, the `handle` argument is the event loop that this listener will
     /// be bound to.
+    /// Use `Handle::default()` to lazily bind to an event loop, just like `bind` does.
     ///
     /// The platform specific behavior of this function looks like:
     ///

tokio-tcp/src/stream.rs

@@ -69,8 +69,7 @@ impl TcpStream {
     ///
     /// This function will convert a TCP stream created by the standard library
     /// to a TCP stream ready to be used with the provided event loop handle.
-    /// The stream returned is associated with the event loop and ready to
-    /// perform I/O.
+    /// Use `Handle::default()` to lazily bind to an event loop, just like `connect` does.
     pub fn from_std(stream: net::TcpStream, handle: &Handle)
         -> io::Result<TcpStream>
     {

tokio-udp/src/socket.rs

@@ -36,6 +36,8 @@ impl UdpSocket {
     /// This can be used in conjunction with net2's `UdpBuilder` interface to
     /// configure a socket before it's handed off, such as setting options like
     /// `reuse_address` or binding to multiple addresses.
+    ///
+    /// Use `Handle::default()` to lazily bind to an event loop, just like `bind` does.
     pub fn from_std(socket: net::UdpSocket,
                     handle: &Handle) -> io::Result<UdpSocket> {
         let io = mio::net::UdpSocket::from_socket(socket)?;