From 7e483cc356cff98aa6776bae5de2a4dcdcd420d5 Mon Sep 17 00:00:00 2001
From: Rob Ede <robjtede@icloud.com>
Date: Sat, 20 Feb 2021 17:34:04 +0000
Subject: [PATCH] tweak task and stream docs

---
 actix-rt/src/lib.rs     | 19 +++++++++----------
 actix-utils/src/task.rs | 36 ++++++++++++++----------------------
 2 files changed, 23 insertions(+), 32 deletions(-)

diff --git a/actix-rt/src/lib.rs b/actix-rt/src/lib.rs
index 1649a8b0..a529bdb0 100644
--- a/actix-rt/src/lib.rs
+++ b/actix-rt/src/lib.rs
@@ -70,28 +70,27 @@ pub mod signal {
 }
 
 pub mod net {
-    //! TCP/UDP/Unix bindings (Tokio re-exports).
+    //! TCP/UDP/Unix bindings (mostly Tokio re-exports).
 
+    use std::task::{Context, Poll};
+
+    use tokio::io::{AsyncRead, AsyncWrite};
     pub use tokio::net::UdpSocket;
     pub use tokio::net::{TcpListener, TcpStream};
 
     #[cfg(unix)]
     pub use tokio::net::{UnixDatagram, UnixListener, UnixStream};
 
-    use std::task::{Context, Poll};
-
-    use tokio::io::{AsyncRead, AsyncWrite};
-
-    /// Trait for generic over tokio stream types and various wrapper types around them.
+    /// Extension trait over async read+write types that can also signal readiness.
     pub trait ActixStream: AsyncRead + AsyncWrite + Unpin + 'static {
-        /// poll stream and check read readiness of Self.
+        /// Poll stream and check read readiness of Self.
         ///
-        /// See [tokio::net::TcpStream::poll_read_ready] for detail
+        /// See [tokio::net::TcpStream::poll_read_ready] for detail on intended use.
         fn poll_read_ready(&self, cx: &mut Context<'_>) -> Poll<std::io::Result<()>>;
 
-        /// poll stream and check write readiness of Self.
+        /// Poll stream and check write readiness of Self.
         ///
-        /// See [tokio::net::TcpStream::poll_write_ready] for detail
+        /// See [tokio::net::TcpStream::poll_write_ready] for detail on intended use.
         fn poll_write_ready(&self, cx: &mut Context<'_>) -> Poll<std::io::Result<()>>;
     }
 
diff --git a/actix-utils/src/task.rs b/actix-utils/src/task.rs
index d40ed286..d0793488 100644
--- a/actix-utils/src/task.rs
+++ b/actix-utils/src/task.rs
@@ -1,38 +1,30 @@
-use core::cell::Cell;
-use core::fmt;
-use core::marker::PhantomData;
-use core::task::Waker;
+use core::{cell::Cell, fmt, marker::PhantomData, task::Waker};
 
 /// A synchronization primitive for task wakeup.
 ///
-/// Sometimes the task interested in a given event will change over time.
-/// An `LocalWaker` can coordinate concurrent notifications with the consumer
-/// potentially "updating" the underlying task to wake up. This is useful in
-/// scenarios where a computation completes in another task and wants to
-/// notify the consumer, but the consumer is in the process of being migrated to
-/// a new logical task.
+/// Sometimes the task interested in a given event will change over time. A `LocalWaker` can
+/// coordinate concurrent notifications with the consumer, potentially "updating" the underlying
+/// task to wake up. This is useful in scenarios where a computation completes in another task and
+/// wants to notify the consumer, but the consumer is in the process of being migrated to a new
+/// logical task.
 ///
-/// Consumers should call `register` before checking the result of a computation
-/// and producers should call `wake` after producing the computation (this
-/// differs from the usual `thread::park` pattern). It is also permitted for
-/// `wake` to be called **before** `register`. This results in a no-op.
+/// Consumers should call [`register`] before checking the result of a computation and producers
+/// should call `wake` after producing the computation (this differs from the usual `thread::park`
+/// pattern). It is also permitted for [`wake`] to be called _before_ [`register`]. This results in
+/// a no-op.
 ///
-/// A single `AtomicWaker` may be reused for any number of calls to `register` or
-/// `wake`.
+/// A single `LocalWaker` may be reused for any number of calls to [`register`] or [`wake`].
 #[derive(Default)]
 pub struct LocalWaker {
     pub(crate) waker: Cell<Option<Waker>>,
     // mark LocalWaker as a !Send type.
-    _t: PhantomData<*const ()>,
+    _phantom: PhantomData<*const ()>,
 }
 
 impl LocalWaker {
-    /// Create an `LocalWaker`.
+    /// Creates a new, empty `LocalWaker`.
     pub fn new() -> Self {
-        LocalWaker {
-            waker: Cell::new(None),
-            _t: PhantomData,
-        }
+        LocalWaker::default()
     }
 
     /// Registers the waker to be notified on calls to `wake`.