Missing poll_ready admonition in docs

[JonathanWilbur]

In the code below that I copied from the latest version, if start_send requires calling poll_ready, doesn't it logically follow that directly calling try_send would also require calling poll_ready since the former trivially calls the latter? This was undocumented: I just happened to look at the implementation for these to determine which I should call (which also isn't clear).

impl<T> Sender<T> {
    /// Attempts to send a message on this `Sender`, returning the message
    /// if there was an error.
    pub fn try_send(&mut self, msg: T) -> Result<(), TrySendError<T>> {
        if let Some(inner) = &mut self.0 {
            inner.try_send(msg)
        } else {
            Err(TrySendError { err: SendError { kind: SendErrorKind::Disconnected }, val: msg })
        }
    }

    /// Send a message on the channel.
    ///
    /// This function should only be called after
    /// [`poll_ready`](Sender::poll_ready) has reported that the channel is
    /// ready to receive a message.
    pub fn start_send(&mut self, msg: T) -> Result<(), SendError> {
        self.try_send(msg).map_err(|e| e.err)
    }

    // truncated here for readability
}

[JonathanWilbur]

Maybe this is related, or maybe you consider this a separate issue, but the examples don't even call poll_ready before sending over MPSC.

[oconnor663]

I think what the docs are getting at is, if you call start_send and it turns out the channel is full, you don't get your item back. So in practice, the majority of callers need to wait to call start_send until poll_ready has told them it cannot fail (at least not unless the receiver is dropped in the meantime). But if somehow you don't actually care about dropping items on the floor, then it seems like there isn't anything inherently broken about yolo'ing start_send.