Updated Documentation for Signals

tokio/src/signal/unix.rs

@@ -292,7 +292,11 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> {
     }
 }
 
-/// A stream of events for receiving a particular type of OS signal.
+/// An event for receiving a particular type of OS signal.
+///
+/// The signal can be turned into a `Stream` using [`SignalStream`].
+///
+/// [`SignalStream`]: https://docs.rs/tokio-stream/latest/tokio_stream/wrappers/struct.SignalStream.html
 ///
 /// In general signal handling on Unix is a pretty tricky topic, and this
 /// structure is no exception! There are some important limitations to keep in
@@ -307,9 +311,6 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> {
 ///   Once `poll` has been called, however, a further signal is guaranteed to
 ///   be yielded as an item.
 ///
-///   Put another way, any element pulled off the returned stream corresponds to
-///   *at least one* signal, but possibly more.
-///
 /// * Signal handling in general is relatively inefficient. Although some
 ///   improvements are possible in this crate, it's recommended to not plan on
 ///   having millions of signal channels open.
@@ -345,11 +346,11 @@ fn signal_enable(signal: SignalKind, handle: &Handle) -> io::Result<()> {
 /// #[tokio::main]
 /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
 ///     // An infinite stream of hangup signals.
-///     let mut stream = signal(SignalKind::hangup())?;
+///     let mut sig = signal(SignalKind::hangup())?;
 ///
 ///     // Print whenever a HUP signal is received
 ///     loop {
-///         stream.recv().await;
+///         sig.recv().await;
 ///         println!("got signal HUP");
 ///     }
 /// }
@@ -360,7 +361,7 @@ pub struct Signal {
     inner: RxFuture,
 }
 
-/// Creates a new stream which will receive notifications when the current
+/// Creates a new signal which will receive notifications when the current
 /// process receives the specified signal `kind`.
 ///
 /// This function will create a new stream which binds to the default reactor.

tokio/src/signal/windows.rs

@@ -22,7 +22,7 @@ pub(crate) use self::imp::{OsExtraData, OsStorage};
 #[path = "windows/stub.rs"]
 mod imp;
 
-/// Creates a new stream which receives "ctrl-c" notifications sent to the
+/// Creates a new event which receives "ctrl-c" notifications sent to the
 /// process.
 ///
 /// # Examples
@@ -50,14 +50,18 @@ pub fn ctrl_c() -> io::Result<CtrlC> {
     })
 }
 
-/// Represents a stream which receives "ctrl-c" notifications sent to the process
+/// Represents an event which receives "ctrl-c" notifications sent to the process
 /// via `SetConsoleCtrlHandler`.
 ///
-/// A notification to this process notifies *all* streams listening for
+/// This event can be turned into a `Stream` using [`CtrlCStream`].
+///
+/// [`CtrlCStream`]: https://docs.rs/tokio-stream/latest/tokio_stream/wrappers/struct.CtrlCStream.html
+///
+/// A notification to this process notifies *all* receivers for
 /// this event. Moreover, the notifications **are coalesced** if they aren't processed
 /// quickly enough. This means that if two notifications are received back-to-back,
-/// then the stream may only receive one item about the two notifications.
-#[must_use = "streams do nothing unless polled"]
+/// then the receiver may only receive one item about the two notifications.
+#[must_use = "events do nothing unless polled"]
 #[derive(Debug)]
 pub struct CtrlC {
     inner: RxFuture,
@@ -66,7 +70,7 @@ pub struct CtrlC {
 impl CtrlC {
     /// Receives the next signal notification event.
     ///
-    /// `None` is returned if no more events can be received by this stream.
+    /// `None` is returned if no more events can be received by the `RxFuture`.
     ///
     /// # Examples
     ///
@@ -75,12 +79,11 @@ impl CtrlC {
     ///
     /// #[tokio::main]
     /// async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    ///     // An infinite stream of CTRL-C events.
-    ///     let mut stream = ctrl_c()?;
+    ///     let mut signal = ctrl_c()?;
     ///
     ///     // Print whenever a CTRL-C event is received.
     ///     for countdown in (0..3).rev() {
-    ///         stream.recv().await;
+    ///         signal.recv().await;
     ///         println!("got CTRL-C. {} more to exit", countdown);
     ///     }
     ///
@@ -94,7 +97,7 @@ impl CtrlC {
     /// Polls to receive the next signal notification event, outside of an
     /// `async` context.
     ///
-    /// `None` is returned if no more events can be received by this stream.
+    /// `None` is returned if no more events can be received.
     ///
     /// # Examples
     ///
@@ -127,11 +130,15 @@ impl CtrlC {
 /// Represents a stream which receives "ctrl-break" notifications sent to the process
 /// via `SetConsoleCtrlHandler`.
 ///
-/// A notification to this process notifies *all* streams listening for
+/// This event can be turned into a `Stream` using [`CtrlBreakStream`].
+///
+/// [`CtrlBreakStream`]: https://docs.rs/tokio-stream/latest/tokio_stream/wrappers/struct.CtrlBreakStream.html
+///
+/// A notification to this process notifies *all* receivers for
 /// this event. Moreover, the notifications **are coalesced** if they aren't processed
 /// quickly enough. This means that if two notifications are received back-to-back,
-/// then the stream may only receive one item about the two notifications.
-#[must_use = "streams do nothing unless polled"]
+/// then the receiver may only receive one item about the two notifications.
+#[must_use = "events do nothing unless polled"]
 #[derive(Debug)]
 pub struct CtrlBreak {
     inner: RxFuture,