tweak task and stream docs

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};
+    /// Extension trait over async read+write types that can also signal readiness.
-
-    use tokio::io::{AsyncRead, AsyncWrite};
-
-    /// Trait for generic over tokio stream types and various wrapper types around them.
     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<()>>;
     }
 

actix-utils/src/task.rs

@@ -1,38 +1,30 @@
-use core::cell::Cell;
+use core::{cell::Cell, fmt, marker::PhantomData, task::Waker};
-use core::fmt;
-use core::marker::PhantomData;
-use core::task::Waker;
 
 /// A synchronization primitive for task wakeup.
 ///
-/// Sometimes the task interested in a given event will change over time.
+/// Sometimes the task interested in a given event will change over time. A `LocalWaker` can
-/// An `LocalWaker` can coordinate concurrent notifications with the consumer
+/// coordinate concurrent notifications with the consumer, potentially "updating" the underlying
-/// potentially "updating" the underlying task to wake up. This is useful in
+/// task to wake up. This is useful in scenarios where a computation completes in another task and
-/// scenarios where a computation completes in another task and wants to
+/// wants to notify the consumer, but the consumer is in the process of being migrated to a new
-/// notify the consumer, but the consumer is in the process of being migrated to
+/// logical task.
-/// a new logical task.
 ///
-/// Consumers should call `register` before checking the result of a computation
+/// Consumers should call [`register`] before checking the result of a computation and producers
-/// and producers should call `wake` after producing the computation (this
+/// should call `wake` after producing the computation (this differs from the usual `thread::park`
-/// differs from the usual `thread::park` pattern). It is also permitted for
+/// pattern). It is also permitted for [`wake`] to be called _before_ [`register`]. This results in
-/// `wake` to be called **before** `register`. This results in a no-op.
+/// a no-op.
 ///
-/// A single `AtomicWaker` may be reused for any number of calls to `register` or
+/// A single `LocalWaker` may be reused for any number of calls to [`register`] or [`wake`].
-/// `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 {
+        LocalWaker::default()
-            waker: Cell::new(None),
-            _t: PhantomData,
-        }
     }
 
     /// Registers the waker to be notified on calls to `wake`.