Merge pull request #5040 from yangjie11/comments

[kernel]Normalized kernel API annotation

src/idle.c

@@ -68,14 +68,13 @@ static struct rt_semaphore system_sem;
 static void (*idle_hook_list[RT_IDLE_HOOK_LIST_SIZE])(void);
 
 /**
- * @ingroup Hook
- * This function sets a hook function to idle thread loop. When the system performs
- * idle loop, this hook function should be invoked.
+ * @brief This function sets a hook function to idle thread loop. When the system performs
+ *        idle loop, this hook function should be invoked.
  *
- * @param hook the specified hook function
+ * @param hook the specified hook function.
  *
- * @return RT_EOK: set OK
- *         -RT_EFULL: hook list is full
+ * @return RT_EOK: set OK.
+ *         -RT_EFULL: hook list is full.
  *
  * @note the hook function must be simple and never be blocked or suspend.
  */
@@ -104,12 +103,12 @@ rt_err_t rt_thread_idle_sethook(void (*hook)(void))
 }
 
 /**
- * delete the idle hook on hook list
+ * @brief delete the idle hook on hook list.
  *
- * @param hook the specified hook function
+ * @param hook the specified hook function.
  *
- * @return RT_EOK: delete OK
- *         -RT_ENOSYS: hook was not found
+ * @return RT_EOK: delete OK.
+ *         -RT_ENOSYS: hook was not found.
  */
 rt_err_t rt_thread_idle_delhook(void (*hook)(void))
 {
@@ -153,8 +152,10 @@ rt_inline int _idle_has_defunct_thread(void)
 }
 #endif /* RT_USING_MODULE */
 
-/* enqueue a thread to defunct queue
- * it must be called between rt_hw_interrupt_disable and rt_hw_interrupt_enable
+/**
+ * @brief Enqueue a thread to defunct queue.
+ *
+ * @note It must be called between rt_hw_interrupt_disable and rt_hw_interrupt_enable
  */
 void rt_thread_defunct_enqueue(rt_thread_t thread)
 {
@@ -164,8 +165,10 @@ void rt_thread_defunct_enqueue(rt_thread_t thread)
 #endif
 }
 
-/* dequeue a thread from defunct queue
- * it must be called between rt_hw_interrupt_disable and rt_hw_interrupt_enable
+/**
+ * @brief Dequeue a thread from defunct queue.
+ *
+ * @note It must be called between rt_hw_interrupt_disable and rt_hw_interrupt_enable.
  */
 rt_thread_t rt_thread_defunct_dequeue(void)
 {
@@ -183,9 +186,7 @@ rt_thread_t rt_thread_defunct_dequeue(void)
 }
 
 /**
- * @ingroup Thread
- *
- * This function will perform system background job when system idle.
+ * @brief This function will perform system background job when system idle.
  */
 static void rt_defunct_execute(void)
 {
@@ -316,9 +317,7 @@ static void rt_thread_system_entry(void *parameter)
 #endif
 
 /**
- * @ingroup SystemInit
- *
- * This function will initialize idle thread, then start it.
+ * @brief This function will initialize idle thread, then start it.
  *
  * @note this function must be invoked when system init.
  */
@@ -365,10 +364,7 @@ void rt_thread_idle_init(void)
 }
 
 /**
- * @ingroup Thread
- *
- * This function will get the handler of the idle thread.
- *
+ * @brief This function will get the handler of the idle thread.
  */
 rt_thread_t rt_thread_idle_gethandler(void)
 {

src/mem.c

@@ -66,10 +66,10 @@ static void (*rt_free_hook)(void *ptr);
 /**@{*/
 
 /**
- * This function will set a hook function, which will be invoked when a memory
- * block is allocated from heap memory.
+ * @brief This function will set a hook function, which will be invoked when a memory
+ *        block is allocated from heap memory.
  *
- * @param hook the hook function
+ * @param hook the hook function.
  */
 void rt_malloc_sethook(void (*hook)(void *ptr, rt_size_t size))
 {
@@ -77,8 +77,8 @@ void rt_malloc_sethook(void (*hook)(void *ptr, rt_size_t size))
 }
 
 /**
- * This function will set a hook function, which will be invoked when a memory
- * block is released to heap memory.
+ * @brief This function will set a hook function, which will be invoked when a memory
+ *        block is released to heap memory.
  *
  * @param hook the hook function
  */
@@ -194,11 +194,10 @@ static void plug_holes(struct heap_mem *mem)
 }
 
 /**
- * @ingroup SystemInit
- *
- * This function will initialize system heap memory.
+ * @brief This function will initialize system heap memory.
  *
  * @param begin_addr the beginning address of system heap memory.
+ *
  * @param end_addr the end address of system heap memory.
  */
 void rt_system_heap_init(void *begin_addr, void *end_addr)
@@ -263,11 +262,11 @@ void rt_system_heap_init(void *begin_addr, void *end_addr)
 /**@{*/
 
 /**
- * Allocate a block of memory with a minimum of 'size' bytes.
+ * @brief Allocate a block of memory with a minimum of 'size' bytes.
  *
  * @param size is the minimum size of the requested block in bytes.
  *
- * @return pointer to allocated memory or NULL if no free memory was found.
+ * @return the pointer to allocated memory or NULL if no free memory was found.
  */
 void *rt_malloc(rt_size_t size)
 {
@@ -411,12 +410,13 @@ void *rt_malloc(rt_size_t size)
 RTM_EXPORT(rt_malloc);
 
 /**
- * This function will change the previously allocated memory block.
+ * @brief This function will change the size of previously allocated memory block.
  *
- * @param rmem pointer to memory allocated by rt_malloc
- * @param newsize the required new size
+ * @param rmem is the pointer to memory allocated by rt_malloc.
  *
- * @return the changed memory block address
+ * @param newsize is the required new size.
+ *
+ * @return the changed memory block address.
  */
 void *rt_realloc(void *rmem, rt_size_t newsize)
 {
@@ -517,16 +517,17 @@ void *rt_realloc(void *rmem, rt_size_t newsize)
 RTM_EXPORT(rt_realloc);
 
 /**
- * This function will contiguously allocate enough space for count objects
- * that are size bytes of memory each and returns a pointer to the allocated
- * memory.
+ * @brief  This function will contiguously allocate enough space for count objects
+ *         that are size bytes of memory each and returns a pointer to the allocated
+ *         memory.
  *
- * The allocated memory is filled with bytes of value zero.
+ * @note   The allocated memory is filled with bytes of value zero.
  *
- * @param count number of objects to allocate
- * @param size size of the objects to allocate
+ * @param  count is the number of objects to allocate.
  *
- * @return pointer to allocated memory / NULL pointer if there is an error
+ * @param  size is the size of one object to allocate.
+ *
+ * @return pointer to allocated memory / NULL pointer if there is an error.
  */
 void *rt_calloc(rt_size_t count, rt_size_t size)
 {
@@ -544,10 +545,10 @@ void *rt_calloc(rt_size_t count, rt_size_t size)
 RTM_EXPORT(rt_calloc);
 
 /**
- * This function will release the previously allocated memory block by
- * rt_malloc. The released memory block is taken back to system heap.
+ * @brief This function will release the previously allocated memory block by
+ *        rt_malloc. The released memory block is taken back to system heap.
  *
- * @param rmem the address of memory which will be released
+ * @param rmem the address of memory which will be released.
  */
 void rt_free(void *rmem)
 {
@@ -616,6 +617,16 @@ void rt_free(void *rmem)
 RTM_EXPORT(rt_free);
 
 #ifdef RT_MEM_STATS
+/**
+* @brief This function will caculate the total memory, the used memory, and
+*        the max used memory.
+*
+* @param total is a pointer to get the total size of the memory.
+*
+* @param used is a pointer to get the size of memory used.
+*
+* @param max_used is a pointer to get the maximum memory used.
+*/
 void rt_memory_info(rt_uint32_t *total,
                     rt_uint32_t *used,
                     rt_uint32_t *max_used)

src/mempool.c

@@ -32,8 +32,8 @@ static void (*rt_mp_free_hook)(struct rt_mempool *mp, void *block);
 /**@{*/
 
 /**
- * This function will set a hook function, which will be invoked when a memory
- * block is allocated from memory pool.
+ * @brief This function will set a hook function, which will be invoked when a memory
+ *        block is allocated from the memory pool.
  *
  * @param hook the hook function
  */
@@ -43,8 +43,8 @@ void rt_mp_alloc_sethook(void (*hook)(struct rt_mempool *mp, void *block))
 }
 
 /**
- * This function will set a hook function, which will be invoked when a memory
- * block is released to memory pool.
+ * @brief This function will set a hook function, which will be invoked when a memory
+ *        block is released to the memory pool.
  *
  * @param hook the hook function
  */
@@ -63,14 +63,18 @@ void rt_mp_free_sethook(void (*hook)(struct rt_mempool *mp, void *block))
 /**@{*/
 
 /**
- * This function will initialize a memory pool object, normally which is used
- * for static object.
+ * @brief  This function will initialize a memory pool object, normally which is used
+ *         for static object.
  *
- * @param mp the memory pool object
- * @param name the name of memory pool
- * @param start the star address of memory pool
- * @param size the total size of memory pool
- * @param block_size the size for each block
+ * @param  mp is the memory pool object.
+ *
+ * @param  name is the name of the memory pool.
+ *
+ * @param  start is the start address of the memory pool.
+ *
+ * @param  size is the total size of the memory pool.
+ *
+ * @param  block_size is the size for each block..
  *
  * @return RT_EOK
  */
@@ -125,9 +129,9 @@ rt_err_t rt_mp_init(struct rt_mempool *mp,
 RTM_EXPORT(rt_mp_init);
 
 /**
- * This function will detach a memory pool from system object management.
+ * @brief  This function will detach a memory pool from system object management.
  *
- * @param mp the memory pool object
+ * @param  mp is the memory pool object.
  *
  * @return RT_EOK
  */
@@ -172,12 +176,14 @@ RTM_EXPORT(rt_mp_detach);
 
 #ifdef RT_USING_HEAP
 /**
- * This function will create a mempool object and allocate the memory pool from
- * heap.
+ * @brief This function will create a mempool object and allocate the memory pool from
+ *        heap.
  *
- * @param name the name of memory pool
- * @param block_count the count of blocks in memory pool
- * @param block_size the size for each block
+ * @param name is the name of memory pool.
+ *
+ * @param block_count is the count of blocks in memory pool.
+ *
+ * @param block_size is the size for each block.
  *
  * @return the created mempool object
  */
@@ -241,9 +247,9 @@ rt_mp_t rt_mp_create(const char *name,
 RTM_EXPORT(rt_mp_create);
 
 /**
- * This function will delete a memory pool and release the object memory.
+ * @brief This function will delete a memory pool and release the object memory.
  *
- * @param mp the memory pool object
+ * @param mp is the memory pool object.
  *
  * @return RT_EOK
  */
@@ -293,12 +299,14 @@ RTM_EXPORT(rt_mp_delete);
 #endif /* RT_USING_HEAP */
 
 /**
- * This function will allocate a block from memory pool
+ * @brief This function will allocate a block from memory pool.
  *
- * @param mp the memory pool object
- * @param time the waiting time
+ * @param mp is the memory pool object.
  *
- * @return the allocated memory block or RT_NULL on allocated failed
+ * @param time is the maximum waiting time for allocating memory.
+ *             - 0 for not waiting, allocating memory immediately.
+ *
+ * @return the allocated memory block or RT_NULL on allocated failed.
  */
 void *rt_mp_alloc(rt_mp_t mp, rt_int32_t time)
 {
@@ -392,9 +400,9 @@ void *rt_mp_alloc(rt_mp_t mp, rt_int32_t time)
 RTM_EXPORT(rt_mp_alloc);
 
 /**
- * This function will release a memory block
+ * @brief This function will release a memory block.
  *
- * @param block the address of memory block to be released
+ * @param block the address of memory block to be released.
  */
 void rt_mp_free(void *block)
 {

src/scheduler.c

@@ -58,19 +58,23 @@ static void (*rt_scheduler_switch_hook)(struct rt_thread *tid);
 /**@{*/
 
 /**
- * This function will set a hook function, which will be invoked when thread
- * switch happens.
+ * @brief This function will set a hook function, which will be invoked when thread
+ *        switch happens.
  *
- * @param hook the hook function
+ * @param hook is the hook function.
  */
-void
-rt_scheduler_sethook(void (*hook)(struct rt_thread *from, struct rt_thread *to))
+void rt_scheduler_sethook(void (*hook)(struct rt_thread *from, struct rt_thread *to))
 {
     rt_scheduler_hook = hook;
 }
 
-void
-rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid))
+/**
+ * @brief This function will set a hook function, which will be invoked when context
+ *        switch happens.
+ *
+ * @param hook is the hook function.
+ */
+void rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid))
 {
     rt_scheduler_switch_hook = hook;
 }
@@ -181,8 +185,7 @@ static struct rt_thread* _scheduler_get_highest_priority_thread(rt_ubase_t *high
 #endif /* RT_USING_SMP */
 
 /**
- * @ingroup SystemInit
- * This function will initialize the system scheduler
+ * @brief This function will initialize the system scheduler.
  */
 void rt_system_scheduler_init(void)
 {
@@ -232,9 +235,8 @@ void rt_system_scheduler_init(void)
 }
 
 /**
- * @ingroup SystemInit
- * This function will startup scheduler. It will select one thread
- * with the highest priority level, then switch to it.
+ * @brief This function will startup the scheduler. It will select one thread
+ *        with the highest priority level, then switch to it.
  */
 void rt_system_scheduler_start(void)
 {
@@ -271,12 +273,13 @@ void rt_system_scheduler_start(void)
 
 #ifdef RT_USING_SMP
 /**
- * This function will handle IPI interrupt and do a scheduling in system;
+ * @brief This function will handle IPI interrupt and do a scheduling in system.
  *
- * @param vector, the number of IPI interrupt for system scheduling
- * @param param, use RT_NULL
+ * @param vector is the number of IPI interrupt for system scheduling.
  *
- * NOTE: this function should be invoke or register as ISR in BSP.
+ * @param param is not used, and can be set to RT_NULL.
+ *
+ * @note this function should be invoke or register as ISR in BSP.
  */
 void rt_scheduler_ipi_handler(int vector, void *param)
 {
@@ -284,9 +287,9 @@ void rt_scheduler_ipi_handler(int vector, void *param)
 }
 
 /**
- * This function will perform one scheduling. It will select one thread
- * with the highest priority level in global ready queue or local ready queue,
- * then switch to it.
+ * @brief This function will perform one scheduling. It will select one thread
+ *        with the highest priority level in global ready queue or local ready queue,
+ *        then switch to it.
  */
 void rt_schedule(void)
 {
@@ -407,8 +410,8 @@ __exit:
 }
 #else
 /**
- * This function will perform one schedule. It will select one thread
- * with the highest priority level, and switch to it immediately.
+ * @brief This function will perform scheduling once. It will select one thread
+ *        with the highest priority, and switch to it immediately.
  */
 void rt_schedule(void)
 {
@@ -536,9 +539,9 @@ __exit:
 #endif /* RT_USING_SMP */
 
 /**
- * This function checks if a scheduling is needed after IRQ context. If yes,
- * it will select one thread with the highest priority level, and then switch
- * to it.
+ * @brief This function checks whether a scheduling is needed after an IRQ context switching. If yes,
+ *        it will select one thread with the highest priority level, and then switch
+ *        to it.
  */
 #ifdef RT_USING_SMP
 void rt_scheduler_do_irq_switch(void *context)
@@ -631,12 +634,13 @@ void rt_scheduler_do_irq_switch(void *context)
 }
 #endif /* RT_USING_SMP */
 
-/*
- * This function will insert a thread to system ready queue. The state of
- * thread will be set as READY and remove from suspend queue.
+/**
+ * @brief This function will insert a thread to the system ready queue. The state of
+ *        thread will be set as READY and the thread will be removed from suspend queue.
  *
- * @param thread the thread to be inserted
- * @note Please do not invoke this function in user application.
+ * @param thread is the thread to be inserted.
+ *
+ * @note  Please do not invoke this function in user application.
  */
 #ifdef RT_USING_SMP
 void rt_schedule_insert_thread(struct rt_thread *thread)
@@ -741,12 +745,12 @@ __exit:
 }
 #endif /* RT_USING_SMP */
 
-/*
- * This function will remove a thread from system ready queue.
+/**
+ * @brief This function will remove a thread from system ready queue.
  *
- * @param thread the thread to be removed
+ * @param thread is the thread to be removed.
  *
- * @note Please do not invoke this function in user application.
+ * @note  Please do not invoke this function in user application.
  */
 #ifdef RT_USING_SMP
 void rt_schedule_remove_thread(struct rt_thread *thread)
@@ -835,7 +839,7 @@ void rt_schedule_remove_thread(struct rt_thread *thread)
 #endif /* RT_USING_SMP */
 
 /**
- * This function will lock the thread scheduler.
+ * @brief This function will lock the thread scheduler.
  */
 #ifdef RT_USING_SMP
 void rt_enter_critical(void)
@@ -897,7 +901,7 @@ void rt_enter_critical(void)
 RTM_EXPORT(rt_enter_critical);
 
 /**
- * This function will unlock the thread scheduler.
+ * @brief This function will unlock the thread scheduler.
  */
 #ifdef RT_USING_SMP
 void rt_exit_critical(void)
@@ -971,7 +975,7 @@ void rt_exit_critical(void)
 RTM_EXPORT(rt_exit_critical);
 
 /**
- * Get the scheduler lock level
+ * @brief Get the scheduler lock level.
  *
  * @return the level of the scheduler lock. 0 means unlocked.
  */

src/slab.c

@@ -74,10 +74,10 @@ static void (*rt_free_hook)(void *ptr);
 /**@{*/
 
 /**
- * This function will set a hook function, which will be invoked when a memory
- * block is allocated from heap memory.
+ * @brief This function will set a hook function, which will be invoked when a memory
+ *        block is allocated from heap memory.
  *
- * @param hook the hook function
+ * @param hook the hook function.
  */
 void rt_malloc_sethook(void (*hook)(void *ptr, rt_size_t size))
 {
@@ -86,8 +86,8 @@ void rt_malloc_sethook(void (*hook)(void *ptr, rt_size_t size))
 RTM_EXPORT(rt_malloc_sethook);
 
 /**
- * This function will set a hook function, which will be invoked when a memory
- * block is released to heap memory.
+ * @brief This function will set a hook function, which will be invoked when a memory
+ *        block is released to heap memory.
  *
  * @param hook the hook function
  */
@@ -233,6 +233,11 @@ struct rt_page_head
 static struct rt_page_head *rt_page_list;
 static struct rt_semaphore heap_sem;
 
+/**
+ * @brief Alloc memory size by page.
+ *
+ * @param npages the number of pages.
+ */
 void *rt_page_alloc(rt_size_t npages)
 {
     struct rt_page_head *b, *n;
@@ -269,6 +274,13 @@ void *rt_page_alloc(rt_size_t npages)
     return b;
 }
 
+/**
+ * @brief Free memory by page.
+ *
+ * @param addr is the head address of first page.
+ *
+ * @param npages is the number of pages.
+ */
 void rt_page_free(void *addr, rt_size_t npages)
 {
     struct rt_page_head *b, *n;
@@ -334,12 +346,11 @@ static void rt_page_init(void *addr, rt_size_t npages)
 }
 
 /**
- * @ingroup SystemInit
+ * @brief This function will init system heap.
  *
- * This function will init system heap
+ * @param begin_addr the beginning address of system page.
  *
- * @param begin_addr the beginning address of system page
- * @param end_addr the end address of system page
+ * @param end_addr the end address of system page.
  */
 void rt_system_heap_init(void *begin_addr, void *end_addr)
 {
@@ -465,15 +476,15 @@ rt_inline int zoneindex(rt_size_t *bytes)
 /**@{*/
 
 /**
- * This function will allocate a block from system heap memory.
- * - If the nbytes is less than zero,
- * or
- * - If there is no nbytes sized memory valid in system,
- * the RT_NULL is returned.
+ * @brief This function will allocate a block from system heap memory.
  *
- * @param size the size of memory to be allocated
+ * @note the RT_NULL is returned if
+ *         - the nbytes is less than zero.
+ *         - there is no nbytes sized memory valid in system.
  *
- * @return the allocated memory
+ * @param size is the size of memory to be allocated.
+ *
+ * @return the allocated memory.
  */
 void *rt_malloc(rt_size_t size)
 {
@@ -668,12 +679,13 @@ __exit:
 RTM_EXPORT(rt_malloc);
 
 /**
- * This function will change the size of previously allocated memory block.
+ * @brief This function will change the size of previously allocated memory block.
  *
- * @param ptr the previously allocated memory block
- * @param size the new size of memory block
+ * @param ptr is the previously allocated memory block.
  *
- * @return the allocated memory
+ * @param size is the new size of memory block.
+ *
+ * @return the allocated memory.
  */
 void *rt_realloc(void *ptr, rt_size_t size)
 {
@@ -736,16 +748,17 @@ void *rt_realloc(void *ptr, rt_size_t size)
 RTM_EXPORT(rt_realloc);
 
 /**
- * This function will contiguously allocate enough space for count objects
- * that are size bytes of memory each and returns a pointer to the allocated
- * memory.
+ * @brief This function will contiguously allocate enough space for count objects
+ *        that are size bytes of memory each and returns a pointer to the allocated
+ *        memory.
  *
- * The allocated memory is filled with bytes of value zero.
+ * @note The allocated memory is filled with bytes of value zero.
  *
- * @param count number of objects to allocate
- * @param size size of the objects to allocate
+ * @param count is the number of objects to allocate.
  *
- * @return pointer to allocated memory / NULL pointer if there is an error
+ * @param size is the size of the objects to allocate.
+ *
+ * @return pointer to allocated memory / NULL pointer if there is an error.
  */
 void *rt_calloc(rt_size_t count, rt_size_t size)
 {
@@ -763,10 +776,11 @@ void *rt_calloc(rt_size_t count, rt_size_t size)
 RTM_EXPORT(rt_calloc);
 
 /**
- * This function will release the previous allocated memory block by rt_malloc.
- * The released memory block is taken back to system heap.
+ * @brief This function will release the previous allocated memory block by rt_malloc.
  *
- * @param ptr the address of memory which will be released
+ * @note The released memory block is taken back to system heap.
+ *
+ * @param ptr is the address of memory which will be released
  */
 void rt_free(void *ptr)
 {
@@ -905,6 +919,16 @@ void rt_free(void *ptr)
 RTM_EXPORT(rt_free);
 
 #ifdef RT_MEM_STATS
+/**
+* @brief This function will caculate the total memory, the used memory, and
+*        the max used memory.
+*
+* @param total is a pointer to get the total size of the memory.
+*
+* @param used is a pointer to get the size of memory used.
+*
+* @param max_used is a pointer to get the maximum memory used.
+*/
 void rt_memory_info(rt_uint32_t *total,
                     rt_uint32_t *used,
                     rt_uint32_t *max_used)