io: doc that AsyncWrite does not inherit from Write (#7705)

tokio/src/io/async_write.rs

@@ -5,9 +5,11 @@ use std::task::{Context, Poll};
 
 /// Writes bytes asynchronously.
 ///
-/// The trait inherits from [`std::io::Write`] and indicates that an I/O object is
+/// This trait is analogous to the [`std::io::Write`] trait, but integrates with
-/// **nonblocking**. All non-blocking I/O objects must return an error when
+/// the asynchronous task system. In particular, the [`poll_write`] method,
-/// bytes cannot be written instead of blocking the current thread.
+/// unlike [`Write::write`], will automatically queue the current task for wakeup
+/// and return if data is not yet available, rather than blocking the calling
+/// thread.
 ///
 /// Specifically, this means that the [`poll_write`] function will return one of
 /// the following:
@@ -25,22 +27,15 @@ use std::task::{Context, Poll};
 /// * `Poll::Ready(Err(e))` for other errors are standard I/O errors coming from the
 ///   underlying object.
 ///
-/// This trait importantly means that the [`write`][stdwrite] method only works in
+/// This trait importantly means that the `write` method only works in the
-/// the context of a future's task. The object may panic if used outside of a task.
+/// context of a future's task. The object may panic if used outside of a task.
-///
-/// Note that this trait also represents that the  [`Write::flush`][stdflush] method
-/// works very similarly to the `write` method, notably that `Ok(())` means that the
-/// writer has successfully been flushed, a "would block" error means that the
-/// current task is ready to receive a notification when flushing can make more
-/// progress, and otherwise normal errors can happen as well.
 ///
 /// Utilities for working with `AsyncWrite` values are provided by
 /// [`AsyncWriteExt`].
 ///
 /// [`std::io::Write`]: std::io::Write
+/// [`Write::write`]: std::io::Write::write()
 /// [`poll_write`]: AsyncWrite::poll_write()
-/// [stdwrite]: std::io::Write::write()
-/// [stdflush]: std::io::Write::flush()
 /// [`AsyncWriteExt`]: crate::io::AsyncWriteExt
 pub trait AsyncWrite {
     /// Attempt to write bytes from `buf` into the object.