1 files changed, 18 insertions, 10 deletions
diff --git a/src/chsem.c b/src/chsem.c
index b5c197b6b..011737642 100644
--- a/src/chsem.c
+++ b/src/chsem.c
@@ -41,7 +41,7 @@ void chSemInit(Semaphore *sp, cnt_t n) {
 /**
  * Performs a reset operation on the semaphore.
  * @param sp pointer to a \p Semaphore structure
- * @param n the new value of the semaphore counter. Must be non-negative.
+ * @param n the new value of the semaphore counter. The value must be non-negative.
  * @note The released threads can recognize they were waked up by a reset
  *       instead than a signal because the \p chSemWait() will return
  *       \p RDY_RESET instead of \p RDY_OK.
@@ -59,7 +59,7 @@ void chSemReset(Semaphore *sp, cnt_t n) {
 /**
  * Performs a reset operation on the semaphore.
  * @param sp pointer to a \p Semaphore structure
- * @param n the new value of the semaphore counter. Must be non-negative.
+ * @param n the new value of the semaphore counter. The value must be non-negative.
  * @note The released threads can recognize they were waked up by a reset
  *       instead than a signal because the \p chSemWait() will return
  *       \p RDY_RESET instead of \p RDY_OK.
@@ -78,7 +78,8 @@ void chSemResetI(Semaphore *sp, cnt_t n) {
 /**
  * Performs a wait operation on a semaphore.
  * @param sp pointer to a \p Semaphore structure
- * @return the function can return \p RDY_OK or \p RDY_RESET.
+ * @retval RDY_OK if the semaphore was signaled or not taken.
+ * @retval RDY_RESET if the semaphore was reset using \p chSemReset().
  */
 msg_t chSemWait(Semaphore *sp) {
   msg_t msg;
@@ -94,7 +95,8 @@ msg_t chSemWait(Semaphore *sp) {
 /**
  * Performs a wait operation on a semaphore.
  * @param sp pointer to a \p Semaphore structure
- * @return the function can return \p RDY_OK or \p RDY_RESET.
+ * @retval RDY_OK if the semaphore was signaled or not taken.
+ * @retval RDY_RESET if the semaphore was reset using \p chSemReset().
  * @note This function must be called with interrupts disabled.
  * @note This function cannot be called by an interrupt handler.
  */
@@ -114,7 +116,12 @@ msg_t chSemWaitS(Semaphore *sp) {
  * Performs a wait operation on a semaphore with timeout specification.
  * @param sp pointer to a \p Semaphore structure
  * @param time the number of ticks before the operation fails
- * @return the function can return \p RDY_OK, \p RDY_TIMEOUT or \p RDY_RESET.
+ * @retval RDY_OK if the semaphore was signaled or not taken.
+ * @retval RDY_RESET if the semaphore was reset using \p chSemReset().
+ * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the specified
+ *         timeout.
+ * @note The function is available only if the \p CH_USE_SEMAPHORES_TIMEOUT
+ *       option is enabled in \p chconf.h.
  */
 msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
   msg_t msg;
@@ -131,9 +138,10 @@ msg_t chSemWaitTimeout(Semaphore *sp, systime_t time) {
  * Performs a wait operation on a semaphore with timeout specification.
  * @param sp pointer to a \p Semaphore structure
  * @param time the number of ticks before the operation fails
- * @return the function can return \p RDY_OK, \p RDY_TIMEOUT or \p RDY_RESET.
- * @note This function must be called with interrupts disabled.
- * @note This function cannot be called by an interrupt handler.
+ * @retval RDY_OK if the semaphore was signaled or not taken.
+ * @retval RDY_RESET if the semaphore was reset using \p chSemReset().
+ * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the specified
+ *         timeout.
  * @note The function is available only if the \p CH_USE_SEMAPHORES_TIMEOUT
  *       option is enabled in \p chconf.h.
  */
@@ -167,7 +175,6 @@ void chSemSignal(Semaphore *sp) {
 /**
  * Performs a signal operation on a semaphore.
  * @param sp pointer to a \p Semaphore structure
- * @note This function must be called with interrupts disabled.
  * @note The function is available only if the \p CH_USE_SEMAPHORES
  *       option is enabled in \p chconf.h.
  * @note This function does not reschedule.
@@ -188,7 +195,8 @@ void chSemSignalI(Semaphore *sp) {
  * Performs atomic signal and wait operations on two semaphores.
  * @param sps pointer to a \p Semaphore structure to be signaled
  * @param spw pointer to a \p Semaphore structure to be wait on
- * @return the function can return \p RDY_OK or \p RDY_RESET.
+ * @retval RDY_OK if the semaphore was signaled or not taken.
+ * @retval RDY_RESET if the semaphore was reset using \p chSemReset().
  * @note The function is available only if the \p CH_USE_SEMSW
  *       option is enabled in \p chconf.h.
  */