docs: update API documentation for some crates (#1380)

Updates API documentation for

- tokio-buf
- tokio-codec
- tokio-current-thread
- tokio-executor

tokio-executor/src/executor.rs

@@ -48,20 +48,20 @@ use std::pin::Pin;
 ///
 /// # Examples
 ///
-/// ```rust
+/// ```
+/// #![feature(async_await)]
+///
 /// use tokio_executor::Executor;
-/// use futures::future::lazy;
 ///
 /// # fn docs(my_executor: &mut dyn Executor) {
-/// my_executor.spawn(Box::new(lazy(|| {
+/// my_executor.spawn(Box::pin(async {
 ///     println!("running on the executor");
-///     Ok(())
-/// }))).unwrap();
+/// })).unwrap();
 /// # }
 /// ```
 ///
 /// [`spawn`]: #tymethod.spawn
-/// [`poll`]: https://docs.rs/futures/0.1/futures/future/trait.Future.html#tymethod.poll
+/// [`poll`]: https://doc.rust-lang.org/std/future/trait.Future.html#tymethod.poll
 /// [`TypedExecutor`]: ../trait.TypedExecutor.html
 pub trait Executor {
     /// Spawns a future object to run on this executor.
@@ -78,15 +78,15 @@ pub trait Executor {
     ///
     /// # Examples
     ///
-    /// ```rust
+    /// ```
+    /// #![feature(async_await)]
+    ///
     /// use tokio_executor::Executor;
-    /// use futures::future::lazy;
     ///
     /// # fn docs(my_executor: &mut dyn Executor) {
-    /// my_executor.spawn(Box::pin(lazy(|| {
+    /// my_executor.spawn(Box::pin(async {
     ///     println!("running on the executor");
-    ///     Ok(())
-    /// }))).unwrap();
+    /// })).unwrap();
     /// # }
     /// ```
     fn spawn(&mut self, future: Pin<Box<dyn Future<Output = ()> + Send>>)
@@ -109,16 +109,16 @@ pub trait Executor {
     ///
     /// # Examples
     ///
-    /// ```rust
+    /// ```
+    /// #![feature(async_await)]
+    ///
     /// use tokio_executor::Executor;
-    /// use futures::future::lazy;
     ///
     /// # fn docs(my_executor: &mut dyn Executor) {
     /// if my_executor.status().is_ok() {
-    ///     my_executor.spawn(Box::pin(lazy(|| {
+    ///     my_executor.spawn(Box::pin(async {
     ///         println!("running on the executor");
-    ///         Ok(())
-    ///     }))).unwrap();
+    ///     })).unwrap();
     /// } else {
     ///     println!("the executor is not in a good state");
     /// }

tokio-executor/src/global.rs

@@ -124,13 +124,11 @@ where
 /// # Examples
 ///
 /// ```no_run
-/// use tokio_executor::spawn;
-/// use futures::future::lazy;
+/// #![feature(async_await)]
 ///
-/// spawn(lazy(|| {
+/// tokio::spawn(async {
 ///     println!("running on the default executor");
-///     Ok(())
-/// }));
+/// });
 /// ```
 pub fn spawn<T>(future: T)
 where

tokio-executor/src/lib.rs

@@ -51,7 +51,7 @@
 //! [`enter`]: fn.enter.html
 //! [`DefaultExecutor`]: struct.DefaultExecutor.html
 //! [`Park`]: park/index.html
-//! [`Future::poll`]: https://docs.rs/futures/0.1/futures/future/trait.Future.html#tymethod.poll
+//! [`Future::poll`]: https://doc.rust-lang.org/std/future/trait.Future.html#tymethod.poll
 
 mod enter;
 mod error;

tokio-executor/src/park.rs

@@ -28,7 +28,7 @@
 //! Some things to note:
 //!
 //! * If [`unpark`] is called before [`park`], the next call to [`park`] will
-//! **not** block the thread.
+//!   **not** block the thread.
 //! * **Spurious** wakeups are permitted, i.e., the [`park`] method may unblock
 //!   even if [`unpark`] was not called.
 //! * [`park_timeout`] does the same as [`park`] but allows specifying a maximum

tokio-executor/src/typed.rs

@@ -20,15 +20,20 @@ use crate::SpawnError;
 /// such, the function takes a stream and an executor on which the background
 /// task is spawned.
 ///
-/// ```rust
-/// use futures::{try_ready, Future, Stream, Poll};
+/// ```
+/// #![feature(async_await)]
+///
 /// use tokio::executor::TypedExecutor;
 /// use tokio::sync::oneshot;
 ///
-/// pub fn drain<T, E>(stream: T, executor: &mut E)
-///     -> impl Future<Item = (), Error = ()>
+/// use futures_core::{ready, Stream};
+/// use std::future::Future;
+/// use std::pin::Pin;
+/// use std::task::{Context, Poll};
+///
+/// async fn drain<T, E>(stream: T, executor: &mut E)
 /// where
-///     T: Stream,
+///     T: Stream + Unpin,
 ///     E: TypedExecutor<Drain<T>>
 /// {
 ///     let (tx, rx) = oneshot::channel();
@@ -38,31 +43,29 @@ use crate::SpawnError;
 ///         tx: Some(tx),
 ///     }).unwrap();
 ///
-///     rx.map_err(|_| ())
+///     rx.await.unwrap()
 /// }
 ///
 /// // The background task
-/// pub struct Drain<T: Stream> {
+/// pub struct Drain<T> {
 ///     stream: T,
 ///     tx: Option<oneshot::Sender<()>>,
 /// }
 ///
-/// impl<T: Stream> Future for Drain<T> {
-///     type Item = ();
-///     type Error = ();
+/// impl<T: Stream + Unpin> Future for Drain<T> {
+///     type Output = ();
 ///
-///     fn poll(&mut self) -> Poll<Self::Item, Self::Error> {
+///     fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
 ///         loop {
-///             let item = try_ready!(
-///                 self.stream.poll()
-///                     .map_err(|_| ())
+///             let item = ready!(
+///                 Pin::new(&mut self.stream).poll_next(cx)
 ///             );
 ///
 ///             if item.is_none() { break; }
 ///         }
 ///
 ///         self.tx.take().unwrap().send(()).map_err(|_| ());
-///         Ok(().into())
+///         Poll::Ready(())
 ///     }
 /// }
 /// ```
@@ -86,7 +89,11 @@ pub trait TypedExecutor<T> {
     ///
     /// ```rust
     /// use tokio_executor::TypedExecutor;
-    /// use futures::{Future, Poll};
+    ///
+    /// use std::future::Future;
+    /// use std::pin::Pin;
+    /// use std::task::{Context, Poll};
+    ///
     /// fn example<T>(my_executor: &mut T)
     /// where
     ///     T: TypedExecutor<MyFuture>,
@@ -97,12 +104,11 @@ pub trait TypedExecutor<T> {
     /// struct MyFuture;
     ///
     /// impl Future for MyFuture {
-    ///     type Item = ();
-    ///     type Error = ();
+    ///     type Output = ();
     ///
-    ///     fn poll(&mut self) -> Poll<(), ()> {
+    ///     fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<()> {
     ///         println!("running on the executor");
-    ///         Ok(().into())
+    ///         Poll::Ready(())
     ///     }
     /// }
     /// ```
@@ -127,7 +133,10 @@ pub trait TypedExecutor<T> {
     ///
     /// ```rust
     /// use tokio_executor::TypedExecutor;
-    /// use futures::{Future, Poll};
+    ///
+    /// use std::future::Future;
+    /// use std::pin::Pin;
+    /// use std::task::{Context, Poll};
     ///
     /// fn example<T>(my_executor: &mut T)
     /// where
@@ -143,12 +152,11 @@ pub trait TypedExecutor<T> {
     /// struct MyFuture;
     ///
     /// impl Future for MyFuture {
-    ///     type Item = ();
-    ///     type Error = ();
+    ///     type Output = ();
     ///
-    ///     fn poll(&mut self) -> Poll<(), ()> {
+    ///     fn poll(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<()> {
     ///         println!("running on the executor");
-    ///         Ok(().into())
+    ///         Poll::Ready(())
     ///     }
     /// }
     /// ```