Revise documentations

kernel/src/process/signal/pause.rs

@@ -24,12 +24,12 @@ use crate::{
 /// when the waiting thread is interrupted by a POSIX signal.
 /// When this happens, the `pause`-family methods return `Err(EINTR)`.
 pub trait Pause: WaitTimeout {
-    /// Pauses the execution of the current thread until the `cond` is met ( i.e., `cond()`
+    /// Pauses until the condition is met or a signal interrupts.
-    /// returns `Some(_)` ), or some signals are received by the current thread or process.
     ///
     /// # Errors
     ///
-    /// If some signals are received before `cond` is met, this method will return `Err(EINTR)`.
+    /// This method will return an error with [`EINTR`] if a signal is received before the
+    /// condition is met.
     ///
     /// [`EINTR`]: crate::error::Errno::EINTR
     fn pause_until<F, R>(&self, cond: F) -> Result<R>
@@ -39,15 +39,13 @@ pub trait Pause: WaitTimeout {
         self.pause_until_or_timeout_impl(cond, None)
     }
 
-    /// Pauses the execution of the current thread until the `cond` is met ( i.e., `cond()`
+    /// Pauses until the condition is met, the timeout is reached, or a signal interrupts.
-    /// returns `Some(_)` ), or some signals are received by the current thread or process,
-    /// or the given `timeout` is expired.
     ///
     /// # Errors
     ///
-    /// If `timeout` is expired before the `cond` is met or some signals are received,
+    /// Before the condition is met, this method will return an error with
-    /// this method will return `Err(ETIME)`. If the pausing is interrupted by some signals,
+    ///  - [`EINTR`] if a signal is received;
-    /// this method will return `Err(EINTR)`
+    ///  - [`ETIME`] if the timeout is reached.
     ///
     /// [`ETIME`]: crate::error::Errno::ETIME
     /// [`EINTR`]: crate::error::Errno::EINTR
@@ -65,15 +63,13 @@ pub trait Pause: WaitTimeout {
         self.pause_until_or_timeout_impl(cond, timeout_inner)
     }
 
-    /// Pauses the execution of the current thread until the `cond` is met ( i.e., `cond()`
+    /// Pauses until the condition is met, the timeout is reached, or a signal interrupts.
-    /// returns `Some(_)` ), or some signals are received by the current thread or process.
-    /// If the input `timeout` is set, the pausing will finish when the `timeout` is expired.
     ///
     /// # Errors
     ///
-    /// If `timeout` is expired before the `cond` is met or some signals are received,
+    /// Before the condition is met, this method will return an error with
-    /// this method will return `Err(ETIME)`. If the pausing is interrupted by some signals,
+    ///  - [`EINTR`] if a signal is received;
-    /// this method will return `Err(EINTR)`
+    ///  - [`ETIME`] if the timeout is reached.
     ///
     /// [`ETIME`]: crate::error::Errno::ETIME
     /// [`EINTR`]: crate::error::Errno::EINTR
@@ -86,14 +82,17 @@ pub trait Pause: WaitTimeout {
     where
         F: FnMut() -> Option<R>;
 
-    /// Pauses the execution of the current thread until being woken up,
+    /// Pauses until the thread is woken up, the timeout is reached, or a signal interrupts.
-    /// or some signals are received by the current thread or process.
-    /// If the input `timeout` is set, the pausing will finish when the `timeout` is expired.
     ///
     /// # Errors
     ///
-    /// If `timeout` is expired before woken up or some signals are received,
+    /// This method will return an error with [`ETIME`] if the timeout is reached.
-    /// this method will return [`Errno::ETIME`].
+    ///
+    /// Unlike other methods in the trait, this method will _not_ return an error with [`EINTR`] if
+    /// a signal is received (FIXME).
+    ///
+    /// [`ETIME`]: crate::error::Errno::ETIME
+    /// [`EINTR`]: crate::error::Errno::EINTR
     fn pause_timeout<'a>(&self, timeout: impl Into<TimeoutExt<'a>>) -> Result<()>;
 }
 

kernel/src/time/wait.rs

@@ -9,9 +9,14 @@ use crate::prelude::*;
 
 /// A trait that provide the timeout related function for [`Waiter`] and [`WaitQueue`]`.
 pub trait WaitTimeout {
-    /// Waits until some condition returns `Some(_)`, or a given timeout is reached. If
+    /// Waits until some condition returns `Some(_)` or a given timeout is reached.
-    /// the condition does not becomes `Some(_)` before the timeout is reached,
+    ///
-    /// this function will return `ETIME` error.
+    /// # Errors
+    ///
+    /// If the condition does not become `Some(_)` before the timeout is reached, this function
+    /// will return an error with [`ETIME`].
+    ///
+    /// [`ETIME`]: crate::error::Errno::ETIME
     fn wait_until_or_timeout<'a, F, T, R>(&self, mut cond: F, timeout: T) -> Result<R>
     where
         F: FnMut() -> Option<R>,
@@ -26,10 +31,15 @@ pub trait WaitTimeout {
         self.wait_until_or_timeout_cancelled(cond, || Ok(()), timeout_inner)
     }
 
-    /// Waits until some condition returns `Some(_)`, or be cancelled due to
+    /// Waits until some condition returns `Some(_)` or is cancelled by the timeout or cancel
-    /// reaching the timeout or the inputted cancel condition. If the condition
+    /// condition.
-    /// does not becomes `Some(_)` before the timeout is reached or `cancel_cond`
+    ///
-    /// returns `Err`, this function will return corresponding `Err`.
+    /// # Errors
+    ///
+    /// If the condition does not become `Some(_)` before the cancellation, this function
+    /// will return:
+    ///  - an error with [`ETIME`] if the timeout is reached;
+    ///  - the error returned by the cancel condition if the cancel condition returns `Err(_)`.
     #[doc(hidden)]
     fn wait_until_or_timeout_cancelled<F, R, FCancel>(
         &self,