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

Code before:
//!   [`changed`] will return immediately. If the current value is *seen*, then
//!   it will sleep until either a new message is sent via the [`Sender`] half,
//!   or the [`Sender`] is dropped.
//! * On completion, the [`changed`] method marks the new value as *seen*.
//! * At creation, the initial value is considered *seen*. In other words,
//!   [`Receiver::changed()`] will not return until a subsequent value is sent.
//! * New [`Receiver`] instances can be created with [`Sender::subscribe()`].
//!   The current value at the time the [`Receiver`] is created is considered
//!   *seen*.
//!
//! ## [`changed`] versus [`has_changed`]
//! The [`Receiver`] half provides two methods for checking for changes
//! in the channel, [`has_changed`] and [`changed`].
//!
//! * [`has_changed`] is a *synchronous* method that checks whether the current
//!   value is seen or not and returns a boolean. This method does __not__ mark the
//!   value as seen.
//!
//! * [`changed`] is an *asynchronous* method that will return once an unseen
//!   value is in the channel. This method does mark the value as seen.
//!
//! Note there are two behavioral differences on when these two methods return
//! an error.
//!
//! - [`has_changed`] errors if and only if the channel is closed.
//! - [`changed`] errors if the channel has been closed __AND__
//!   the current value is seen.
//!
//! See the example below that shows how these methods have different fallibility.
//!
//! ## [`borrow_and_update`] versus [`borrow`]
//!
//! If the receiver intends to await notifications from [`changed`] in a loop,
//! [`Receiver::borrow_and_update()`] should be preferred over
//! [`Receiver::borrow()`].  This avoids a potential race where a new value is
//! sent between [`changed`] being ready and the value being read. (If
//! [`Receiver::borrow()`] is used, the loop may run twice with the same value.)
//!
//! If the receiver is only interested in the current value, and does not intend
//! to wait for changes, then [`Receiver::borrow()`] can be used. It may be more
//! convenient to use [`borrow`](Receiver::borrow) since it's an `&self`
//! method---[`borrow_and_update`](Receiver::borrow_and_update) requires `&mut
//! self`.
//!
//! # Examples
//!
//! The following example prints `hello! world! `.
//!
//! ```
//! use tokio::sync::watch;
//! use tokio::time::{Duration, sleep};

Review comment (suggestion):
```suggestion
//! - [`has_changed`] errors as long as the  channel is closed.
```

Code after:
//!   [`changed`] will return immediately. If the current value is *seen*, then
//!   it will sleep until either a new message is sent via the [`Sender`] half,
//!   or the [`Sender`] is dropped.
//! * On completion, the [`changed`] method marks the new value as *seen*.
//! * At creation, the initial value is considered *seen*. In other words,
//!   [`Receiver::changed()`] will not return until a subsequent value is sent.
//! * New [`Receiver`] instances can be created with [`Sender::subscribe()`].
//!   The current value at the time the [`Receiver`] is created is considered
//!   *seen*.
//!
//! ## [`changed`] versus [`has_changed`]
//!
//! The [`Receiver`] half provides two methods for checking for changes
//! in the channel, [`has_changed`] and [`changed`].
//!
//! * [`has_changed`] is a *synchronous* method that checks whether the current
//!   value is seen or not and returns a boolean. This method does __not__ mark the
//!   value as seen.
//!
//! * [`changed`] is an *asynchronous* method that will return once an unseen
//!   value is in the channel. This method does mark the value as seen.
//!
//! Note there are two behavioral differences on when these two methods return
//! an error.
//!
//! - [`has_changed`] errors if and only if the channel is closed.
//! - [`changed`] errors if the channel has been closed __AND__
//!   the current value is seen.
//!
//! See the example below that shows how these methods have different fallibility.
//!
//! ## [`borrow_and_update`] versus [`borrow`]
//!
//! If the receiver intends to await notifications from [`changed`] in a loop,
//! [`Receiver::borrow_and_update()`] should be preferred over
//! [`Receiver::borrow()`].  This avoids a potential race where a new value is
//! sent between [`changed`] being ready and the value being read. (If
//! [`Receiver::borrow()`] is used, the loop may run twice with the same value.)
//!
//! If the receiver is only interested in the current value, and does not intend
//! to wait for changes, then [`Receiver::borrow()`] can be used. It may be more
//! convenient to use [`borrow`](Receiver::borrow) since it's an `&self`
//! method---[`borrow_and_update`](Receiver::borrow_and_update) requires `&mut
//! self`.
//!
//! # Examples
//!
//! The following example prints `hello! world! `.
//!
//! ```
//! use tokio::sync::watch;