From c33a21509affaf366deee896fb1f9575fb73168f Mon Sep 17 00:00:00 2001
From: Huang Xilong <41188334+ddAkira@users.noreply.github.com>
Date: Sat, 10 Jun 2023 12:41:21 +0800
Subject: [PATCH] [comment][libc] add some comments for functions in
 posix_signal (#7647)

---
 components/libc/posix/signal/posix_signal.c | 49 ++++++++++++++++++---
 1 file changed, 43 insertions(+), 6 deletions(-)

diff --git a/components/libc/posix/signal/posix_signal.c b/components/libc/posix/signal/posix_signal.c
index 04b3b104f1..25475bdbad 100644
--- a/components/libc/posix/signal/posix_signal.c
+++ b/components/libc/posix/signal/posix_signal.c
@@ -44,7 +44,6 @@ void (*signal(int sig, void (*func)(int))) (int)
  *
  * @return   Returns 0 on success.
  */
-
 int sigprocmask (int how, const sigset_t *set, sigset_t *oset)
 {
     rt_base_t level;
@@ -90,7 +89,16 @@ int sigpending (sigset_t *set)
     sigprocmask(SIG_SETMASK, RT_NULL, set);
     return 0;
 }
-
+/**
+ * @brief    This function will temporarily replace the signal mask of the calling thread
+ *           with the mask given and then suspends the thread until delivery of an expected signal
+ *           or a signal whose action is to terminate a process.
+ *
+ * @param    set is a pointer of a sigset_t object that is used to replace the original mask of the calling thread.
+ *
+ * @return   Returns 0 on success.
+ *           If the return value is any other values, it means that the signal wait failed.
+ */
 int sigsuspend (const sigset_t *set)
 {
     int ret  = 0;
@@ -125,7 +133,6 @@ int sigsuspend (const sigset_t *set)
  *
  * @return   Returns 0 on success or -1 on failure.
  */
-
 int sigaction(int signum, const struct sigaction *act, struct sigaction *oldact)
 {
     rt_sighandler_t old = RT_NULL;
@@ -145,7 +152,19 @@ int sigaction(int signum, const struct sigaction *act, struct sigaction *oldact)
 
     return 0;
 }
-
+/**
+ * @brief    This function will suspends execution of the calling thread until one of
+ *           the signals in the given set is pending. If none of the signals specified
+ *           are pending, it will wait for the specified time interval.
+ *
+ * @param    set is the set of signal values to be waited for.
+ *
+ * @param    info is a pointer to the received signal info.
+ *
+ * @param    timeout is a pointer to a timespec structure that specifys the waiting time.
+ *
+ * @return   Return 0 on success. Otherwise, return -1 and set errno to indicate the error.
+ */
 int sigtimedwait(const sigset_t *set, siginfo_t *info, const struct timespec *timeout)
 {
     int ret  = 0;
@@ -162,7 +181,16 @@ int sigtimedwait(const sigset_t *set, siginfo_t *info, const struct timespec *ti
     errno = ret;
     return -1;
 }
-
+/**
+ * @brief    This function will suspend execution of the calling thread until one of
+ *           the specified signal becomes pending and return the signal number.
+ *
+ * @param    set is the set of signal values to be waited for.
+ *
+ * @param    sig is a pointer to the received signal number.
+ *
+ * @return   Return 0 on success or -1 on failure.
+ */
 int sigwait(const sigset_t *set, int *sig)
 {
     siginfo_t si;
@@ -172,7 +200,16 @@ int sigwait(const sigset_t *set, int *sig)
     *sig = si.si_signo;
     return 0;
 }
-
+/**
+ * @brief    This function will suspend execution of the calling thread until one of
+ *           the specified signal is pending.
+ *
+ * @param    set is the set of signal values to be waited for.
+ *
+ * @param    info is a pointer to the received signal info.
+ *
+ * @return   Return 0 on success or -1 on failure.
+ */
 int sigwaitinfo(const sigset_t *set, siginfo_t *info)
 {
     return sigtimedwait(set, info, NULL);
-- 
GitLab