Repository: tokio-rs/tokio
File: tokio/src/io/async_fd.rs (Rust)

Code before:
            .field("inner", &self.inner)
            .finish()
    }
}

impl<T: AsRawFd> Drop for AsyncFd<T> {
    fn drop(&mut self) {
        let _ = self.take_inner();
    }
}

impl<'a, Inner: AsRawFd> AsyncFdReadyGuard<'a, Inner> {
    /// Indicates to tokio that the file descriptor is no longer ready. All
    /// internal readiness flags will be cleared, and tokio will wait for the
    /// next edge-triggered readiness notification from the OS.
    ///
    /// This function is commonly used with guards returned by [`AsyncFd::readable`] and
    /// [`AsyncFd::writable`].
    ///
    /// It is critical that this function not be called unless your code
    /// _actually observes_ that the file descriptor is _not_ ready. Do not call
    /// it simply because, for example, a read succeeded; it should be called
    /// when a read is observed to block.
    ///
    /// Note that that if a readiness notification occurs following the last operation
    /// but prior to invoking `clear_ready`, it will not be cleared.
    pub fn clear_ready(&mut self) {
        if let Some(event) = self.event.take() {
            self.async_fd.registration.clear_readiness(event);
        }
    }

    /// Indicates to tokio that the file descriptor no longer has a specific readiness.
    /// The internal readiness flag will be cleared, and tokio will wait for the
    /// next edge-triggered readiness notification from the OS.
    /// This implies that if a readiness notification occurs following the last operation
    /// but prior to invoking `clear_ready`, it will not be cleared.
    ///
    /// This function is useful in combination with the [`AsyncFd::ready`] method when a
    /// combined interest like `Interest::READABLE | Interest::WRITABLE` is used.
    ///
    /// It is critical that this function not be called unless your code
    /// _actually observes_ that the file descriptor is _not_ ready for the provided `Ready`.
    /// Do not call it simply because, for example, a read succeeded; it should be called
    /// when a read is observed to block. Only clear the specific readiness that is observed to
    /// block. For example when a read blocks when using a combined interest,
    /// only clear `Ready::READABLE`.
    ///
    /// Note that that if a readiness notification occurs following the last operation
    /// but prior to invoking `clear_ready`, it will not be cleared.    
    ///

Review comment (suggestion):
I think it's really important to be very clear in the wording here, because the point we are making is tricky to understand.

Here's one suggested wording. This one tries to explain it twice with "in other words". I still don't love it though.
```suggestion
    /// This method only clears readiness events that happened before the creation of this guard. In other words, if the IO resource becomes ready between the creation of the guard and this call to `clear_ready`, then the readiness is not actually cleared.
```

Code after:
            .field("inner", &self.inner)
            .finish()
    }
}

impl<T: AsRawFd> Drop for AsyncFd<T> {
    fn drop(&mut self) {
        let _ = self.take_inner();
    }
}

impl<'a, Inner: AsRawFd> AsyncFdReadyGuard<'a, Inner> {
    /// Indicates to tokio that the file descriptor is no longer ready. All
    /// internal readiness flags will be cleared, and tokio will wait for the
    /// next edge-triggered readiness notification from the OS.
    ///
    /// This function is commonly used with guards returned by [`AsyncFd::readable`] and
    /// [`AsyncFd::writable`].
    ///
    /// It is critical that this function not be called unless your code
    /// _actually observes_ that the file descriptor is _not_ ready. Do not call
    /// it simply because, for example, a read succeeded; it should be called
    /// when a read is observed to block.
    ///
    /// This method only clears readiness events that happened before the creation of this guard.
    /// In other words, if the IO resource becomes ready between the creation of the guard and
    /// this call to `clear_ready`, then the readiness is not actually cleared.
    pub fn clear_ready(&mut self) {
        if let Some(event) = self.event.take() {
            self.async_fd.registration.clear_readiness(event);
        }
    }

    /// Indicates to tokio that the file descriptor no longer has a specific readiness.
    /// The internal readiness flag will be cleared, and tokio will wait for the
    /// next edge-triggered readiness notification from the OS.
    ///
    /// This function is useful in combination with the [`AsyncFd::ready`] method when a
    /// combined interest like `Interest::READABLE | Interest::WRITABLE` is used.
    ///
    /// It is critical that this function not be called unless your code
    /// _actually observes_ that the file descriptor is _not_ ready for the provided `Ready`.
    /// Do not call it simply because, for example, a read succeeded; it should be called
    /// when a read is observed to block. Only clear the specific readiness that is observed to
    /// block. For example when a read blocks when using a combined interest,
    /// only clear `Ready::READABLE`.
    ///
    /// This method only clears readiness events that happened before the creation of this guard.
    /// In other words, if the IO resource becomes ready between the creation of the guard and
    /// this call to `clear_ready`, then the readiness is not actually cleared.
    ///