Update docs of futures-mio

src/udp.rs

@@ -66,11 +66,21 @@ impl UdpSocket {
     }
 
     /// Test whether this socket is ready to be read or not.
+    ///
+    /// If the socket is *not* readable then the current task is scheduled to
+    /// get a notification when the socket does become readable. That is, this
+    /// is only suitable for calling in a `Future::poll` method and will
+    /// automatically handle ensuring a retry once the socket is readable again.
     pub fn poll_read(&self) -> Poll<(), io::Error> {
         self.ready.poll_read()
     }
 
     /// Test whether this socket is writey to be written to or not.
+    ///
+    /// If the socket is *not* writable then the current task is scheduled to
+    /// get a notification when the socket does become writable. That is, this
+    /// is only suitable for calling in a `Future::poll` method and will
+    /// automatically handle ensuring a retry once the socket is writable again.
     pub fn poll_write(&self) -> Poll<(), io::Error> {
         self.ready.poll_write()
     }