Repository: tokio-rs/tokio
File: tokio/src/sync/mpsc/bounded.rs (Rust)

Code before:
    ///     permit.send(());
    ///     rx.recv().await.unwrap();
    ///     assert_eq!(tx.capacity(), 5);
    /// }
    /// ```
    ///
    /// [`send`]: Sender::send
    /// [`reserve`]: Sender::reserve
    pub fn capacity(&self) -> usize {
        self.chan.semaphore().0.available_permits()
    }

    /// Converts the `Sender` to a [`WeakSender`] that does not count
    /// towards RAII semantics, i.e. if all `Sender` instances of the
    /// channel were dropped and only `WeakSender` instances remain,
    /// the channel is closed.
    pub fn downgrade(&self) -> WeakSender<T> {
        WeakSender {
            chan: self.chan.downgrade(),
        }
    }

    /// Returns the max buffer capacity of the channel.
    ///
    /// The max capacity is the buffer capacity initially specified when calling
    /// [`channel`].
    ///
    /// # Examples
    ///
    /// ```
    /// use tokio::sync::mpsc;
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     let (tx, rx) = mpsc::channel::<()>(5);
    ///      
    ///     // both max capacity and capacity are the same at first
    ///     assert_eq!(tx.max_capacity(), 5);
    ///     assert_eq!(tx.capacity(), 5);
    ///
    ///     // Making a reservation doesn't change the max capacity.
    ///     let permit = tx.reserve().await.unwrap();
    ///     assert_eq!(tx.max_capacity(), 5);
    ///     // but drops the capacity by one
    ///     assert_eq!(tx.capacity(), 4);
    /// }
    /// ```
    ///
    /// [`channel`]: channel
    pub fn max_capacity(&self) -> usize {
        self.chan.semaphore().1

Review comment (suggestion):
maybe we should also discuss how this is distinct from `capacity` here in the docs, as well as in the examples?

perhaps something like this:
```suggestion
    /// The max capacity is the buffer capacity initially specified when calling
    /// [`channel`]. This is distinct from [`capacity`], which returns the *current*
    /// available buffer capacity: as messages are sent and received, the
    /// value returned by [`capacity`] will go up or down, while  `max_capacity`
    /// will always return maximum capacity that was set when the channel was
    /// created.
```

Code after:
    ///
    ///     // Sending and receiving a value increases the capacity by one.
    ///     permit.send(());
    ///     rx.recv().await.unwrap();
    ///     assert_eq!(tx.capacity(), 5);
    /// }
    /// ```
    ///
    /// [`send`]: Sender::send
    /// [`reserve`]: Sender::reserve
    /// [`channel`]: channel
    /// [`max_capacity`]: Sender::max_capacity
    pub fn capacity(&self) -> usize {
        self.chan.semaphore().0.available_permits()
    }

    /// Converts the `Sender` to a [`WeakSender`] that does not count
    /// towards RAII semantics, i.e. if all `Sender` instances of the
    /// channel were dropped and only `WeakSender` instances remain,
    /// the channel is closed.
    pub fn downgrade(&self) -> WeakSender<T> {
        WeakSender {
            chan: self.chan.downgrade(),
        }
    }

    /// Returns the maximum buffer capacity of the channel.
    ///
    /// The maximum capacity is the buffer capacity initially specified when calling
    /// [`channel`]. This is distinct from [`capacity`], which returns the *current*
    /// available buffer capacity: as messages are sent and received, the
    /// value returned by [`capacity`] will go up or down, whereas the value
    /// returned by `max_capacity` will remain constant.
    ///
    /// # Examples
    ///
    /// ```
    /// use tokio::sync::mpsc;
    ///
    /// #[tokio::main]
    /// async fn main() {
    ///     let (tx, _rx) = mpsc::channel::<()>(5);
    ///      
    ///     // both max capacity and capacity are the same at first
    ///     assert_eq!(tx.max_capacity(), 5);
    ///     assert_eq!(tx.capacity(), 5);
    ///
    ///     // Making a reservation doesn't change the max capacity.
    ///     let permit = tx.reserve().await.unwrap();
    ///     assert_eq!(tx.max_capacity(), 5);
    ///     // but drops the capacity by one