Index access depreciated (tokio-rs#713)

* Index access depreciated
* Deprecate return value of Poll:poll in doc

src/poll.rs

@@ -936,14 +936,18 @@ impl Poll {
     ///
     /// `poll` returns the number of readiness events that have been pushed into
     /// `events` or `Err` when an error has been encountered with the system
-    /// selector.
+    /// selector.  The value returned is deprecated and will be removed in 0.7.0.
+    /// Accessing the events by index is also deprecated.  Events can be
+    /// inserted by other events triggering, thus making sequential access
+    /// problematic.  Use the iterator API instead.  See [`iter`].
     ///
     /// See the [struct] level documentation for a higher level discussion of
     /// polling.
     ///
     /// [`readable`]: struct.Ready.html#method.readable
     /// [`writable`]: struct.Ready.html#method.writable
     /// [struct]: #
+    /// [`iter`]: struct.Events.html#method.iter
     ///
     /// # Examples
     ///
@@ -1181,7 +1185,7 @@ impl Poll {
         self.readiness_queue.poll(&mut events.inner);
 
         // Return number of polled events
-        Ok(events.len())
+        Ok(events.inner.len())
     }
 }
 
@@ -1342,49 +1346,14 @@ impl Events {
         }
     }
 
-    /// Returns the `Event` at the given index, or `None` if the index is out of
-    /// bounds.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// # use std::error::Error;
-    /// # fn try_main() -> Result<(), Box<Error>> {
-    /// use mio::{Events, Poll};
-    /// use std::time::Duration;
-    ///
-    /// let mut events = Events::with_capacity(1024);
-    /// let poll = Poll::new()?;
-    ///
-    /// // Register handles with `poll`
-    ///
-    /// let n = poll.poll(&mut events, Some(Duration::from_millis(100)))?;
-    ///
-    /// for i in 0..n {
-    ///     println!("event={:?}", events.get(i).unwrap());
-    /// }
-    /// #     Ok(())
-    /// # }
-    /// #
-    /// # fn main() {
-    /// #     try_main().unwrap();
-    /// # }
-    /// ```
+    #[deprecated(since="0.6.10", note="Index access removed in favor of iterator only API.")]
+    #[doc(hidden)]
     pub fn get(&self, idx: usize) -> Option<Event> {
         self.inner.get(idx)
     }
 
-    /// Returns the number of `Event` values currently in `self`.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// use mio::Events;
-    ///
-    /// let events = Events::with_capacity(1024);
-    ///
-    /// assert_eq!(0, events.len());
-    /// ```
+    #[doc(hidden)]
+    #[deprecated(since="0.6.10", note="Index access removed in favor of iterator only API.")]
     pub fn len(&self) -> usize {
         self.inner.len()
     }
@@ -1465,7 +1434,7 @@ impl<'a> Iterator for Iter<'a> {
     type Item = Event;
 
     fn next(&mut self) -> Option<Event> {
-        let ret = self.inner.get(self.pos);
+        let ret = self.inner.inner.get(self.pos);
         self.pos += 1;
         ret
     }
@@ -1487,7 +1456,7 @@ impl Iterator for IntoIter {
     type Item = Event;
 
     fn next(&mut self) -> Option<Event> {
-        let ret = self.inner.get(self.pos);
+        let ret = self.inner.inner.get(self.pos);
         self.pos += 1;
         ret
     }
@@ -1496,7 +1465,6 @@ impl Iterator for IntoIter {
 impl fmt::Debug for Events {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         f.debug_struct("Events")
-            .field("len", &self.len())
             .field("capacity", &self.capacity())
             .finish()
     }