doxygen: updated doc for thread management subsystem

Signed-off-by: Chen Wang <[email protected]>

1 files changed, 87 insertions, 44 deletions

diff --git a/src/thread.c b/src/thread.c
index a520a323b1..7c3a7e0c65 100644
--- a/src/thread.c
+++ b/src/thread.c
@@ -306,23 +306,39 @@ static rt_err_t _thread_init(struct rt_thread *thread,
  * @brief   This function will initialize a thread. It's used to initialize a
  *          static thread object.
  *
- * @param   thread is the static thread object.
+ * @param   thread Thread handle. Thread handle is provided by the user and
+ *                 points to the corresponding thread control block memory address.
  *
- * @param   name is the name of thread, which shall be unique.
+ * @param   name Name of the thread (shall be unique); the maximum length of the
+ *               thread name is specified by the `RT_NAME_MAX` macro defined in
+ *               `rtconfig.h`, and the extra part is automatically truncated.
  *
- * @param   entry is the entry function of thread.
+ * @param   entry Entry function of thread.
  *
- * @param   parameter is the parameter of thread enter function.
+ * @param   parameter Parameter of thread entry function.
  *
- * @param   stack_start is the start address of thread stack.
+ * @param   stack_start Start address of thread stack.
  *
- * @param   stack_size is the size of thread stack.
+ * @param   stack_size Size of thread stack in bytes. Stack space address
+ *                     alignment is required in most systems (for example,
+ *                     alignment to 4-byte addresses in the ARM architecture).
  *
- * @param   priority is the priority of thread.
+ * @param   priority Priority of thread. The priority range is based on the
+ *                   system configuration (macro definition `RT_THREAD_PRIORITY_MAX`
+ *                   in `rtconfig.h`). If 256 levels of priority are supported,
+ *                   the range is from 0 to 255. The smaller the value, the
+ *                   higher the priority, and 0 is the highest priority.
  *
- * @param   tick is the time slice if there are same priority thread.
+ * @param   tick Time slice if there are same priority thread. The unit of the
+ *               time slice (tick) is the tick of the operating system. When
+ *               there are threads with the same priority in the system, this
+ *               parameter specifies the maximum length of time of a thread for
+ *               one schedule. At the end of this time slice run, the scheduler
+ *               automatically selects the next ready state of the same priority
+ *               thread to run.
  *
- * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ * @return  Return the operation status. If the return value is `RT_EOK`, the
+ *          function is successfully executed.
  *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_init(struct rt_thread *thread,
@@ -359,7 +375,8 @@ RTM_EXPORT(rt_thread_init);
 /**
  * @brief   This function will return self thread object.
  *
- * @return  The self thread object.
+ * @return  The self thread object. If returns `RT_NULL`, it means that the
+ *          scheduler has not started yet.
  */
 rt_thread_t rt_thread_self(void)
 {
@@ -385,9 +402,10 @@ RTM_EXPORT(rt_thread_self);
 /**
  * @brief   This function will start a thread and put it to system ready queue.
  *
- * @param   thread is the thread to be started.
+ * @param   thread Handle of the thread to be started.
  *
- * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ * @return  Return the operation status. If the return value is `RT_EOK`, the
+ *          function is successfully executed.
  *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_startup(rt_thread_t thread)
@@ -462,9 +480,11 @@ static rt_err_t _thread_detach(rt_thread_t thread);
  * @brief   This function will detach a thread. The thread object will be removed from
  *          thread queue and detached/deleted from the system object management.
  *
- * @param   thread is the thread to be deleted.
+ * @param   thread Handle of the thread to be deleted. The thread must be
+ *                 initialized by `rt_thread_init()`.
  *
- * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ * @return  Return the operation status. If the return value is `RT_EOK`, the
+ *          function is successfully executed.
  *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_detach(rt_thread_t thread)
@@ -505,20 +525,32 @@ static rt_err_t _thread_detach(rt_thread_t thread)
  * @brief   This function will create a thread object and allocate thread object memory.
  *          and stack.
  *
- * @param   name is the name of thread, which shall be unique.
+ * @param   name The name of the thread (shall be unique.); the maximum length of
+ *               the thread name is specified by macro `RT_NAME_MAX` in `rtconfig.h`,
+ *               and the extra part is automatically truncated.
  *
- * @param   entry is the entry function of thread.
+ * @param   entry Entry function of thread.
  *
- * @param   parameter is the parameter of thread enter function.
+ * @param   parameter Parameter of thread entry function.
  *
- * @param   stack_size is the size of thread stack.
+ * @param   stack_size Size of thread stack in bytes.
  *
- * @param   priority is the priority of thread.
+ * @param   priority Priority of thread. The priority range is based on the
+ *                   system configuration (macro definition `RT_THREAD_PRIORITY_MAX`
+ *                   in rtconfig.h). If 256-level priority is supported, then
+ *                   the range is from 0 to 255. The smaller the value, the
+ *                   higher the priority, and 0 is the highest priority.
  *
- * @param   tick is the time slice if there are same priority thread.
+ * @param   tick Time slice if there are same priority thread. The unit of the
+ *               time slice (tick) is the tick of the operating system. When
+ *               there are threads with the same priority in the system, this
+ *               parameter specifies the maximum length of time of a thread for
+ *               one schedule. At the end of this time slice run, the scheduler
+ *               automatically selects the next ready state of the same priority
+ *               thread to run.
  *
- * @return  If the return value is a rt_thread structure pointer, the function is successfully executed.
- *          If the return value is RT_NULL, it means this operation failed.
+ * @return  If the return value is a `rt_thread` structure pointer, the function is successfully executed.
+ *          If the return value is `RT_NULL`, it means this operation failed.
  */
 rt_thread_t rt_thread_create(const char *name,
                              void (*entry)(void *parameter),
@@ -564,9 +596,10 @@ RTM_EXPORT(rt_thread_create);
  * @brief   This function will delete a thread. The thread object will be removed from
  *          thread queue and deleted from system object management in the idle thread.
  *
- * @param   thread is the thread to be deleted.
+ * @param   thread Handle of the thread to be deleted.
  *
- * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ * @return  Return the operation status. If the return value is `RT_EOK`, the
+ *          function is successfully executed.
  *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_delete(rt_thread_t thread)
@@ -668,9 +701,10 @@ static rt_err_t _thread_sleep(rt_tick_t tick)
 /**
  * @brief   This function will let current thread delay for some ticks.
  *
- * @param   tick is the delay ticks.
+ * @param   tick The delay ticks, in units of 1 OS Tick.
  *
- * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ * @return  Return the operation status. If the return value is `RT_EOK`, the
+ *          function is successfully executed.
  *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_delay(rt_tick_t tick)
@@ -746,9 +780,10 @@ RTM_EXPORT(rt_thread_delay_until);
 /**
  * @brief   This function will let current thread delay for some milliseconds.
  *
- * @param   ms is the delay ms time.
+ * @param   ms The delay time in units of 1ms.
  *
- * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ * @return  Return the operation status. If the return value is `RT_EOK`, the
+ *          function is successfully executed.
  *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_mdelay(rt_int32_t ms)
@@ -767,23 +802,21 @@ RTM_EXPORT(rt_thread_mdelay);
 /**
  * @brief   This function will control thread behaviors according to control command.
  *
- * @param   thread is the specified thread to be controlled.
- *
- * @param   cmd is the control command, which includes.
- *
- *              RT_THREAD_CTRL_CHANGE_PRIORITY for changing priority level of thread.
- *
- *              RT_THREAD_CTRL_STARTUP for starting a thread.
+ * @param   thread Handle of the thread to be controlled.
  *
- *              RT_THREAD_CTRL_CLOSE for delete a thread.
+ * @param   cmd Control command, which includes.
+ *              - `RT_THREAD_CTRL_CHANGE_PRIORITY` for changing priority level of thread.
+ *              - `RT_THREAD_CTRL_STARTUP` for starting a thread, equivalent to
+ *                the `rt_thread_startup()` function call.
+ *              - `RT_THREAD_CTRL_CLOSE` for closing a thread, equivalent to the
+ *                `rt_thread_delete()` function call.
+ *              - `RT_THREAD_CTRL_BIND_CPU` for bind the thread to a CPU.
+ *              - `RT_THREAD_CTRL_RESET_PRIORITY` for reset priority level of thread.
  *
- *              RT_THREAD_CTRL_BIND_CPU for bind the thread to a CPU.
+ * @param   arg Argument of control command.
  *
- *              RT_THREAD_CTRL_RESET_PRIORITY for reset priority level of thread.
- *
- * @param   arg is the argument of control command.
- *
- * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ * @return  Return the operation status. If the return value is `RT_EOK`, the
+ *          function is successfully executed.
  *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_control(rt_thread_t thread, int cmd, void *arg)
@@ -1006,6 +1039,15 @@ rt_err_t rt_thread_suspend_with_flag(rt_thread_t thread, int suspend_flag)
 }
 RTM_EXPORT(rt_thread_suspend_with_flag);
 
+/**
+ * @brief   This function will suspend the specified thread and change it to suspend state.
+ *
+ * @param   thread Handle of the thread to be suspended.
+ *
+ * @return  Return the operation status. If the return value is `RT_EOK`, the
+ *          function is successfully executed.
+ *          If the return value is any other values, it means this operation failed.
+ */
 rt_err_t rt_thread_suspend(rt_thread_t thread)
 {
     return rt_thread_suspend_with_flag(thread, RT_UNINTERRUPTIBLE);
@@ -1015,9 +1057,10 @@ RTM_EXPORT(rt_thread_suspend);
 /**
  * @brief   This function will resume a thread and put it to system ready queue.
  *
- * @param   thread is the thread to be resumed.
+ * @param   thread Handle of the thread to be resumed.
  *
- * @return  Return the operation status. If the return value is RT_EOK, the function is successfully executed.
+ * @return  Return the operation status. If the return value is `RT_EOK`, the
+ *          function is successfully executed.
  *          If the return value is any other values, it means this operation failed.
  */
 rt_err_t rt_thread_resume(rt_thread_t thread)