doc: expand mpsc::Sender::send API documentation (#1865)

Includes more description, lists errors, and examples.

Closes #1579

tokio/src/sync/mpsc/bounded.rs

@@ -181,8 +181,68 @@ impl<T> Sender<T> {
         self.chan.poll_ready(cx).map_err(|_| ClosedError::new())
     }
 
-    /// Attempts to send a message on this `Sender`, returning the message
-    /// if there was an error.
+    /// Attempts to immediately send a message on this `Sender`
+    ///
+    /// This method differs from [`send`] by returning immediately if the channel's
+    /// buffer is full or no receiver is waiting to acquire some data. Compared
+    /// with [`send`], this function has two failure cases instead of one (one for
+    /// disconnection, one for a full buffer).
+    ///
+    /// This function may be paired with [`poll_ready`] in order to wait for
+    /// channel capacity before trying to send a value.
+    ///
+    /// # Errors
+    ///
+    /// If the channel capacity has been reached, i.e., the channel has `n`
+    /// buffered values where `n` is the argument passed to [`channel`], then an
+    /// error is returned.
+    ///
+    /// If the receive half of the channel is closed, either due to [`close`]
+    /// being called or the [`Receiver`] handle dropping, the function returns
+    /// an error. The error includes the value passed to `send`.
+    ///
+    /// [`send`]: Sender::send
+    /// [`poll_ready`]: Sender::poll_ready
+    /// [`channel`]: channel
+    /// [`close`]: Receiver::close
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use tokio::sync::mpsc;
+    ///
+    /// #[tokio::main]
+    /// async fn main() {
+    ///     // Create a channel with buffer size 1
+    ///     let (mut tx1, mut rx) = mpsc::channel(1);
+    ///     let mut tx2 = tx1.clone();
+    ///
+    ///     tokio::spawn(async move {
+    ///         tx1.send(1).await.unwrap();
+    ///         tx1.send(2).await.unwrap();
+    ///         // task waits until the receiver receives a value.
+    ///     });
+    ///
+    ///     tokio::spawn(async move {
+    ///         // This will return an error and send
+    ///         // no message if the buffer is full
+    ///         let _ = tx2.try_send(3);
+    ///     });
+    ///
+    ///     let mut msg;
+    ///     msg = rx.recv().await.unwrap();
+    ///     println!("message {} received", msg);
+    ///
+    ///     msg = rx.recv().await.unwrap();
+    ///     println!("message {} received", msg);
+    ///
+    ///     // Third message may have never been sent
+    ///     match rx.recv().await {
+    ///         Some(msg) => println!("message {} received", msg),
+    ///         None => println!("the third message was never sent"),
+    ///     }
+    /// }
+    /// ```
     pub fn try_send(&mut self, message: T) -> Result<(), TrySendError<T>> {
         self.chan.try_send(message)?;
         Ok(())
@@ -190,6 +250,23 @@ impl<T> Sender<T> {
 
     /// Send a value, waiting until there is capacity.
     ///
+    /// A successful send occurs when it is determined that the other end of the
+    /// channel has not hung up already. An unsuccessful send would be one where
+    /// the corresponding receiver has already been closed. Note that a return
+    /// value of `Err` means that the data will never be received, but a return
+    /// value of `Ok` does not mean that the data will be received. It is
+    /// possible for the corresponding receiver to hang up immediately after
+    /// this function returns `Ok`.
+    ///
+    /// # Errors
+    ///
+    /// If the receive half of the channel is closed, either due to [`close`]
+    /// being called or the [`Receiver`] handle dropping, the function returns
+    /// an error. The error includes the value passed to `send`.
+    ///
+    /// [`close`]: Receiver::close
+    /// [`Receiver`]: Receiver
+    ///
     /// # Examples
     ///
     /// In the following example, each call to `send` will block until the