sync: document that there is no spsc and spmc channel (#5306)

tokio/src/sync/broadcast.rs

@@ -18,6 +18,9 @@
 //! returned [`Receiver`] will receive values sent **after** the call to
 //! `subscribe`.
 //!
+//! This channel is also suitable for the single-producer multi-consumer
+//! use-case, where a single sender broadcasts values to many receivers.
+//!
 //! ## Lagging
 //!
 //! As sent messages must be retained until **all** [`Receiver`] handles receive

tokio/src/sync/mod.rs

@@ -94,6 +94,10 @@
 //! producers to a single consumer. This channel is often used to send work to a
 //! task or to receive the result of many computations.
 //!
+//! This is also the channel you should use if you want to send many messages
+//! from a single producer to a single consumer. There is no dedicated spsc
+//! channel.
+//!
 //! **Example:** using an mpsc to incrementally stream the results of a series
 //! of computations.
 //!
@@ -244,6 +248,10 @@
 //! This channel tends to be used less often than `oneshot` and `mpsc` but still
 //! has its use cases.
 //!
+//! This is also the channel you should use if you want to broadcast values from
+//! a single producer to many consumers. There is no dedicated spmc broadcast
+//! channel.
+//!
 //! Basic usage
 //!
 //! ```

tokio/src/sync/mpsc/mod.rs

@@ -21,6 +21,9 @@
 //! when additional capacity is available. In other words, the channel provides
 //! backpressure.
 //!
+//! This channel is also suitable for the single-producer single-consumer
+//! use-case. (Unless you only need to send one message, in which case you
+//! should use the [oneshot] channel.)
 //!
 //! # Disconnection
 //!
@@ -62,7 +65,7 @@
 //! in mind, but they can also be generalized to other kinds of channels. In
 //! general, any channel method that isn't marked async can be called anywhere,
 //! including outside of the runtime. For example, sending a message on a
-//! oneshot channel from outside the runtime is perfectly fine.
+//! [oneshot] channel from outside the runtime is perfectly fine.
 //!
 //! # Multiple runtimes
 //!
@@ -82,6 +85,7 @@
 //! [blocking-recv]: crate::sync::mpsc::Receiver::blocking_recv()
 //! [`UnboundedSender`]: crate::sync::mpsc::UnboundedSender
 //! [`UnboundedReceiver`]: crate::sync::mpsc::UnboundedReceiver
+//! [oneshot]: crate::sync::oneshot
 //! [`Handle::block_on`]: crate::runtime::Handle::block_on()
 //! [std-unbounded]: std::sync::mpsc::channel
 //! [crossbeam-unbounded]: https://docs.rs/crossbeam/*/crossbeam/channel/fn.unbounded.html