From a912a2f88f6b765885a6139be3ce42c388e8b767 Mon Sep 17 00:00:00 2001
From: yangjie <yangjiexaut@126.com>
Date: Fri, 10 Sep 2021 15:55:08 +0800
Subject: [PATCH 1/4] [kernel]Normalized kernel API annotation

---
 src/device.c    | 110 +++++++++++++++++++++++++++---------------------
 src/idle.c      |  44 +++++++++----------
 src/mem.c       |  55 ++++++++++++++----------
 src/mempool.c   |  41 ++++++++++--------
 src/object.c    |  94 ++++++++++++++++++++++-------------------
 src/scheduler.c |  59 ++++++++++++++------------
 src/slab.c      |  82 +++++++++++++++++++++++-------------
 7 files changed, 275 insertions(+), 210 deletions(-)

diff --git a/src/device.c b/src/device.c
index a9c244d306..2c1d31f23e 100644
--- a/src/device.c
+++ b/src/device.c
@@ -39,11 +39,13 @@
 #endif /* RT_USING_DEVICE_OPS */
 
 /**
- * This function registers a device driver with specified name.
+ * @brief This function registers a device driver with specified name.
  *
- * @param dev the pointer of device driver structure
- * @param name the device driver's name
- * @param flags the capabilities flag of device
+ * @param dev the pointer of device driver structure.
+ *
+ * @param name the device driver's name.
+ *
+ * @param flags the capabilities flag of device.
  *
  * @return the error code, RT_EOK on initialization successfully.
  */
@@ -72,9 +74,9 @@ rt_err_t rt_device_register(rt_device_t dev,
 RTM_EXPORT(rt_device_register);
 
 /**
- * This function removes a previously registered device driver
+ * @brief This function removes a previously registered device driver.
  *
- * @param dev the pointer of device driver structure
+ * @param dev the pointer of device driver structure.
  *
  * @return the error code, RT_EOK on successfully.
  */
@@ -91,9 +93,9 @@ rt_err_t rt_device_unregister(rt_device_t dev)
 RTM_EXPORT(rt_device_unregister);
 
 /**
- * This function finds a device driver by specified name.
+ * @brief This function finds a device driver by specified name.
  *
- * @param name the device driver's name
+ * @param name the device driver's name.
  *
  * @return the registered device driver on successful, or RT_NULL on failure.
  */
@@ -105,10 +107,11 @@ RTM_EXPORT(rt_device_find);
 
 #ifdef RT_USING_HEAP
 /**
- * This function creates a device object with user data size.
+ * @brief This function creates a device object with user data size.
  *
- * @param type, the kind type of this device object.
- * @param attach_size, the size of user data.
+ * @param type the kind type of this device object.
+ *
+ * @param attach_size the size of user data.
  *
  * @return the allocated device object, or RT_NULL when failed.
  */
@@ -134,9 +137,9 @@ rt_device_t rt_device_create(int type, int attach_size)
 RTM_EXPORT(rt_device_create);
 
 /**
- * This function destroy the specific device object.
+ * @brief This function destroy the specific device object.
  *
- * @param dev, the specific device object.
+ * @param dev the specific device object.
  */
 void rt_device_destroy(rt_device_t dev)
 {
@@ -153,11 +156,11 @@ RTM_EXPORT(rt_device_destroy);
 #endif /* RT_USING_HEAP */
 
 /**
- * This function will initialize the specified device
+ * @brief This function will initialize the specified device.
  *
- * @param dev the pointer of device driver structure
+ * @param dev the pointer of device driver structure.
  *
- * @return the result
+ * @return the result, RT_EOK on successfully.
  */
 rt_err_t rt_device_init(rt_device_t dev)
 {
@@ -187,12 +190,13 @@ rt_err_t rt_device_init(rt_device_t dev)
 }
 
 /**
- * This function will open a device
+ * @brief This function will open a device.
  *
- * @param dev the pointer of device driver structure
- * @param oflag the flags for device open
+ * @param dev the pointer of device driver structure.
  *
- * @return the result
+ * @param oflag the flags for device open.
+ *
+ * @return the result, RT_EOK on successfully.
  */
 rt_err_t rt_device_open(rt_device_t dev, rt_uint16_t oflag)
 {
@@ -253,11 +257,11 @@ rt_err_t rt_device_open(rt_device_t dev, rt_uint16_t oflag)
 RTM_EXPORT(rt_device_open);
 
 /**
- * This function will close a device
+ * @brief This function will close a device.
  *
- * @param dev the pointer of device driver structure
+ * @param dev the pointer of device driver structure.
  *
- * @return the result
+ * @return the result, RT_EOK on successfully.
  */
 rt_err_t rt_device_close(rt_device_t dev)
 {
@@ -289,12 +293,15 @@ rt_err_t rt_device_close(rt_device_t dev)
 RTM_EXPORT(rt_device_close);
 
 /**
- * This function will read some data from a device.
+ * @brief This function will read some data from a device.
  *
- * @param dev the pointer of device driver structure
- * @param pos the position of reading
- * @param buffer the data buffer to save read data
- * @param size the size of buffer
+ * @param dev the pointer of device driver structure.
+ *
+ * @param pos the position of reading.
+ *
+ * @param buffer the data buffer to save read data.
+ *
+ * @param size the size of buffer.
  *
  * @return the actually read size on successful, otherwise negative returned.
  *
@@ -328,12 +335,15 @@ rt_size_t rt_device_read(rt_device_t dev,
 RTM_EXPORT(rt_device_read);
 
 /**
- * This function will write some data to a device.
+ * @brief This function will write some data to a device.
  *
- * @param dev the pointer of device driver structure
- * @param pos the position of written
- * @param buffer the data buffer to be written to device
- * @param size the size of buffer
+ * @param dev the pointer of device driver structure.
+ *
+ * @param pos the position of written.
+ *
+ * @param buffer the data buffer to be written to device.
+ *
+ * @param size the size of buffer.
  *
  * @return the actually written size on successful, otherwise negative returned.
  *
@@ -367,13 +377,15 @@ rt_size_t rt_device_write(rt_device_t dev,
 RTM_EXPORT(rt_device_write);
 
 /**
- * This function will perform a variety of control functions on devices.
+ * @brief This function will perform a variety of control functions on devices.
  *
- * @param dev the pointer of device driver structure
- * @param cmd the command sent to device
- * @param arg the argument of command
+ * @param dev the pointer of device driver structure.
  *
- * @return the result
+ * @param cmd the command sent to device.
+ *
+ * @param arg the argument of command.
+ *
+ * @return the result, -RT_ENOSYS for failed.
  */
 rt_err_t rt_device_control(rt_device_t dev, int cmd, void *arg)
 {
@@ -391,13 +403,14 @@ rt_err_t rt_device_control(rt_device_t dev, int cmd, void *arg)
 RTM_EXPORT(rt_device_control);
 
 /**
- * This function will set the reception indication callback function. This callback function
- * is invoked when this device receives data.
+ * @brief This function will set the reception indication callback function. This callback function
+ *        is invoked when this device receives data.
  *
- * @param dev the pointer of device driver structure
- * @param rx_ind the indication callback function
+ * @param dev the pointer of device driver structure.
  *
- * @return RT_EOK
+ * @param rx_ind the indication callback function.
+ *
+ * @return RT_EOK.
  */
 rt_err_t
 rt_device_set_rx_indicate(rt_device_t dev,
@@ -413,13 +426,14 @@ rt_device_set_rx_indicate(rt_device_t dev,
 RTM_EXPORT(rt_device_set_rx_indicate);
 
 /**
- * This function will set the indication callback function when device has
- * written data to physical hardware.
+ * @brief This function will set the indication callback function when device has
+ *        written data to physical hardware.
  *
- * @param dev the pointer of device driver structure
- * @param tx_done the indication callback function
+ * @param dev the pointer of device driver structure.
  *
- * @return RT_EOK
+ * @param tx_done the indication callback function.
+ *
+ * @return RT_EOK.
  */
 rt_err_t
 rt_device_set_tx_complete(rt_device_t dev,
diff --git a/src/idle.c b/src/idle.c
index ec625cb4a1..4bf89c38e0 100644
--- a/src/idle.c
+++ b/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)
 {
diff --git a/src/mem.c b/src/mem.c
index 20ac0e588c..0fefb86f89 100644
--- a/src/mem.c
+++ b/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,7 +262,7 @@ 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.
  *
@@ -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 previously allocated memory block.
  *
- * @param rmem pointer to memory allocated by rt_malloc
- * @param newsize the required new size
+ * @param rmem pointer to memory allocated by rt_malloc.
  *
- * @return the changed memory block address
+ * @param newsize 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 number of objects to allocate.
  *
- * @return pointer to allocated memory / NULL pointer if there is an error
+ * @param size 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)
 {
@@ -544,8 +545,8 @@ 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
  */
@@ -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)
diff --git a/src/mempool.c b/src/mempool.c
index 5ac87d2bc8..9b201c5f89 100644
--- a/src/mempool.c
+++ b/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 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 memory pool.
  *
  * @param hook the hook function
  */
@@ -63,13 +63,17 @@ 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
  *
  * @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 the memory pool object.
  *
  * @return RT_EOK
  */
@@ -172,11 +176,13 @@ 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
  *
  * @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 the memory pool object.
  *
  * @return RT_EOK
  */
@@ -293,12 +299,13 @@ 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 the memory pool object.
  *
- * @return the allocated memory block or RT_NULL on allocated failed
+ * @param time the waiting time.
+ *
+ * @return the allocated memory block or RT_NULL on allocated failed.
  */
 void *rt_mp_alloc(rt_mp_t mp, rt_int32_t time)
 {
@@ -392,7 +399,7 @@ 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
  */
diff --git a/src/object.c b/src/object.c
index 718b0aa5b2..de0140ebfa 100644
--- a/src/object.c
+++ b/src/object.c
@@ -120,10 +120,10 @@ void (*rt_object_put_hook)(struct rt_object *object);
 /**@{*/
 
 /**
- * This function will set a hook function, which will be invoked when object
- * attaches to kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        attaches to kernel object system.
  *
- * @param hook the hook function
+ * @param hook the hook function.
  */
 void rt_object_attach_sethook(void (*hook)(struct rt_object *object))
 {
@@ -131,8 +131,8 @@ void rt_object_attach_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**
- * This function will set a hook function, which will be invoked when object
- * detaches from kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        detaches from kernel object system.
  *
  * @param hook the hook function
  */
@@ -142,17 +142,17 @@ void rt_object_detach_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**
- * This function will set a hook function, which will be invoked when object
- * is taken from kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        is taken from kernel object system.
  *
- * The object is taken means:
- * semaphore - semaphore is taken by thread
- * mutex - mutex is taken by thread
- * event - event is received by thread
- * mailbox - mail is received by thread
- * message queue - message is received by thread
+ *        The object is taken means:
+ *            semaphore - semaphore is taken by thread
+ *            mutex - mutex is taken by thread
+ *            event - event is received by thread
+ *            mailbox - mail is received by thread
+ *            message queue - message is received by thread
  *
- * @param hook the hook function
+ * @param hook the hook function.
  */
 void rt_object_trytake_sethook(void (*hook)(struct rt_object *object))
 {
@@ -160,18 +160,18 @@ void rt_object_trytake_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**
- * This function will set a hook function, which will be invoked when object
- * have been taken from kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        have been taken from kernel object system.
  *
- * The object have been taken means:
- * semaphore - semaphore have been taken by thread
- * mutex - mutex have been taken by thread
- * event - event have been received by thread
- * mailbox - mail have been received by thread
- * message queue - message have been received by thread
- * timer - timer is started
+ *        The object have been taken means:
+ *            semaphore - semaphore have been taken by thread
+ *            mutex - mutex have been taken by thread
+ *            event - event have been received by thread
+ *            mailbox - mail have been received by thread
+ *            message queue - message have been received by thread
+ *            timer - timer is started
  *
- * @param hook the hook function
+ * @param hook the hook function.
  */
 void rt_object_take_sethook(void (*hook)(struct rt_object *object))
 {
@@ -179,8 +179,8 @@ void rt_object_take_sethook(void (*hook)(struct rt_object *object))
 }
 
 /**
- * This function will set a hook function, which will be invoked when object
- * is put to kernel object system.
+ * @brief This function will set a hook function, which will be invoked when object
+ *        is put to kernel object system.
  *
  * @param hook the hook function
  */
@@ -199,7 +199,7 @@ void rt_object_put_sethook(void (*hook)(struct rt_object *object))
 /**@{*/
 
 /**
- * This function will return the specified type of object information.
+ * @brief This function will return the specified type of object information.
  *
  * @param type the type of object, which can be
  *             RT_Object_Class_Thread/Semaphore/Mutex... etc
@@ -219,10 +219,11 @@ rt_object_get_information(enum rt_object_class_type type)
 RTM_EXPORT(rt_object_get_information);
 
 /**
- * This function will return the length of object list in object container.
+ * @brief This function will return the length of object list in object container.
  *
  * @param type the type of object, which can be
  *             RT_Object_Class_Thread/Semaphore/Mutex... etc
+ *
  * @return the length of object list
  */
 int rt_object_get_length(enum rt_object_class_type type)
@@ -248,12 +249,14 @@ int rt_object_get_length(enum rt_object_class_type type)
 RTM_EXPORT(rt_object_get_length);
 
 /**
- * This function will copy the object pointer of the specified type,
- * with the maximum size specified by maxlen.
+ * @brief This function will copy the object pointer of the specified type,
+ *        with the maximum size specified by maxlen.
  *
  * @param type the type of object, which can be
  *             RT_Object_Class_Thread/Semaphore/Mutex... etc
+ *
  * @param pointers the pointers will be saved to
+ *
  * @param maxlen the maximum number of pointers can be saved
  *
  * @return the copied number of object pointers
@@ -290,11 +293,13 @@ int rt_object_get_pointers(enum rt_object_class_type type, rt_object_t *pointers
 RTM_EXPORT(rt_object_get_pointers);
 
 /**
- * This function will initialize an object and add it to object system
- * management.
+ * @brief This function will initialize an object and add it to object system
+ *        management.
  *
  * @param object the specified object to be initialized.
+ *
  * @param type the object type.
+ *
  * @param name the object name. In system, the object's name must be unique.
  */
 void rt_object_init(struct rt_object         *object,
@@ -361,8 +366,8 @@ void rt_object_init(struct rt_object         *object,
 }
 
 /**
- * This function will detach a static object from object system,
- * and the memory of static object is not freed.
+ * @brief This function will detach a static object from object system,
+ *        and the memory of static object is not freed.
  *
  * @param object the specified object to be detached.
  */
@@ -390,9 +395,10 @@ void rt_object_detach(rt_object_t object)
 
 #ifdef RT_USING_HEAP
 /**
- * This function will allocate an object from object system
+ * @brief This function will allocate an object from object system.
  *
  * @param type the type of object
+ *
  * @param name the object name. In system, the object's name must be unique.
  *
  * @return object
@@ -459,7 +465,7 @@ rt_object_t rt_object_allocate(enum rt_object_class_type type, const char *name)
 }
 
 /**
- * This function will delete an object and release object memory.
+ * @brief This function will delete an object and release object memory.
  *
  * @param object the specified object to be deleted.
  */
@@ -491,9 +497,10 @@ void rt_object_delete(rt_object_t object)
 #endif /* RT_USING_HEAP */
 
 /**
- * This function will judge the object is system object or not.
- * Normally, the system object is a static object and the type
- * of object set to RT_Object_Class_Static.
+ * @brief This function will judge the object is system object or not.
+ *
+ * @note  Normally, the system object is a static object and the type
+ *        of object set to RT_Object_Class_Static.
  *
  * @param object the specified object to be judged.
  *
@@ -511,8 +518,8 @@ rt_bool_t rt_object_is_systemobject(rt_object_t object)
 }
 
 /**
- * This function will return the type of object without
- * RT_Object_Class_Static flag.
+ * @brief This function will return the type of object without
+ *        RT_Object_Class_Static flag.
  *
  * @param object the specified object to be get type.
  *
@@ -527,10 +534,11 @@ rt_uint8_t rt_object_get_type(rt_object_t object)
 }
 
 /**
- * This function will find specified name object from object
- * container.
+ * @brief This function will find specified name object from object
+ *        container.
  *
  * @param name the specified name of object.
+ *
  * @param type the type of object
  *
  * @return the found object or RT_NULL if there is no this object
diff --git a/src/scheduler.c b/src/scheduler.c
index bb431e2efe..dc0073d097 100644
--- a/src/scheduler.c
+++ b/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 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 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)
 {
@@ -271,12 +274,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 the number of IPI interrupt for system scheduling.
  *
- * NOTE: this function should be invoke or register as ISR in BSP.
+ * @param param use 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 +288,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 +411,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 one schedule. It will select one thread
+ *        with the highest priority level, and switch to it immediately.
  */
 void rt_schedule(void)
 {
@@ -536,9 +540,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 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.
  */
 #ifdef RT_USING_SMP
 void rt_scheduler_do_irq_switch(void *context)
@@ -631,11 +635,12 @@ 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 system ready queue. The state of
+ *        thread will be set as READY and remove from suspend queue.
  *
  * @param thread the thread to be inserted
+ *
  * @note Please do not invoke this function in user application.
  */
 #ifdef RT_USING_SMP
@@ -835,7 +840,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 +902,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 +976,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.
  */
diff --git a/src/slab.c b/src/slab.c
index ad1dc71811..4225a4d797 100644
--- a/src/slab.c
+++ b/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 the head address of first page.
+ *
+ * @param npages 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 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 the previously allocated memory block.
  *
- * @return the allocated memory
+ * @param size 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 number of objects to allocate.
  *
- * @return pointer to allocated memory / NULL pointer if there is an error
+ * @param size 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,8 +776,9 @@ 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.
+ *
+ * @note The released memory block is taken back to system heap.
  *
  * @param ptr the address of memory which will be released
  */
@@ -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)

From 5de69966704067ade411d1c4aa11bea327f69793 Mon Sep 17 00:00:00 2001
From: yangjie <yangjiexaut@126.com>
Date: Fri, 10 Sep 2021 17:51:52 +0800
Subject: [PATCH 2/4] [kernel]update format

---
 src/idle.c | 2 +-
 src/mem.c  | 4 ++--
 src/slab.c | 4 ++--
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/idle.c b/src/idle.c
index 4bf89c38e0..61f6a5b383 100644
--- a/src/idle.c
+++ b/src/idle.c
@@ -167,7 +167,7 @@ void rt_thread_defunct_enqueue(rt_thread_t thread)
 
 /**
  * @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)
diff --git a/src/mem.c b/src/mem.c
index 0fefb86f89..f661d49118 100644
--- a/src/mem.c
+++ b/src/mem.c
@@ -618,11 +618,11 @@ RTM_EXPORT(rt_free);
 
 #ifdef RT_MEM_STATS
 /**
-* @brief This function will caculate the total memory, the used memory, and 
+* @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.
diff --git a/src/slab.c b/src/slab.c
index 4225a4d797..87acb17da8 100644
--- a/src/slab.c
+++ b/src/slab.c
@@ -920,11 +920,11 @@ RTM_EXPORT(rt_free);
 
 #ifdef RT_MEM_STATS
 /**
-* @brief This function will caculate the total memory, the used memory, and 
+* @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.

From 464d0c5a97a23f3ec89778945da650b251eddebc Mon Sep 17 00:00:00 2001
From: yangjie <yangjiexaut@126.com>
Date: Sat, 11 Sep 2021 16:40:56 +0800
Subject: [PATCH 3/4] [kernel] update comments

---
 src/device.c    | 64 ++++++++++++++++++++++++-------------------------
 src/mem.c       | 22 ++++++++---------
 src/mempool.c   | 39 +++++++++++++++---------------
 src/object.c    | 40 +++++++++++++++----------------
 src/scheduler.c | 35 +++++++++++++--------------
 src/slab.c      | 16 ++++++-------
 6 files changed, 108 insertions(+), 108 deletions(-)

diff --git a/src/device.c b/src/device.c
index 2c1d31f23e..6e22c2b692 100644
--- a/src/device.c
+++ b/src/device.c
@@ -39,13 +39,13 @@
 #endif /* RT_USING_DEVICE_OPS */
 
 /**
- * @brief This function registers a device driver with specified name.
+ * @brief This function registers a device driver with a specified name.
  *
- * @param dev the pointer of device driver structure.
+ * @param dev is the pointer of device driver structure.
  *
- * @param name the device driver's name.
+ * @param name is the device driver's name.
  *
- * @param flags the capabilities flag of device.
+ * @param flags is the capabilities flag of device.
  *
  * @return the error code, RT_EOK on initialization successfully.
  */
@@ -76,7 +76,7 @@ RTM_EXPORT(rt_device_register);
 /**
  * @brief This function removes a previously registered device driver.
  *
- * @param dev the pointer of device driver structure.
+ * @param dev is the pointer of device driver structure.
  *
  * @return the error code, RT_EOK on successfully.
  */
@@ -95,7 +95,7 @@ RTM_EXPORT(rt_device_unregister);
 /**
  * @brief This function finds a device driver by specified name.
  *
- * @param name the device driver's name.
+ * @param name is the device driver's name.
  *
  * @return the registered device driver on successful, or RT_NULL on failure.
  */
@@ -109,9 +109,9 @@ RTM_EXPORT(rt_device_find);
 /**
  * @brief This function creates a device object with user data size.
  *
- * @param type the kind type of this device object.
+ * @param type is the type of the device object.
  *
- * @param attach_size the size of user data.
+ * @param attach_size is the size of user data.
  *
  * @return the allocated device object, or RT_NULL when failed.
  */
@@ -139,7 +139,7 @@ RTM_EXPORT(rt_device_create);
 /**
  * @brief This function destroy the specific device object.
  *
- * @param dev the specific device object.
+ * @param dev is a specific device object.
  */
 void rt_device_destroy(rt_device_t dev)
 {
@@ -158,7 +158,7 @@ RTM_EXPORT(rt_device_destroy);
 /**
  * @brief This function will initialize the specified device.
  *
- * @param dev the pointer of device driver structure.
+ * @param dev is the pointer of device driver structure.
  *
  * @return the result, RT_EOK on successfully.
  */
@@ -192,9 +192,9 @@ rt_err_t rt_device_init(rt_device_t dev)
 /**
  * @brief This function will open a device.
  *
- * @param dev the pointer of device driver structure.
+ * @param dev is the pointer of device driver structure.
  *
- * @param oflag the flags for device open.
+ * @param oflag is the flags for device open.
  *
  * @return the result, RT_EOK on successfully.
  */
@@ -259,7 +259,7 @@ RTM_EXPORT(rt_device_open);
 /**
  * @brief This function will close a device.
  *
- * @param dev the pointer of device driver structure.
+ * @param dev is the pointer of device driver structure.
  *
  * @return the result, RT_EOK on successfully.
  */
@@ -295,13 +295,13 @@ RTM_EXPORT(rt_device_close);
 /**
  * @brief This function will read some data from a device.
  *
- * @param dev the pointer of device driver structure.
+ * @param dev is the pointer of device driver structure.
  *
- * @param pos the position of reading.
+ * @param pos is the position when reading.
  *
- * @param buffer the data buffer to save read data.
+ * @param buffer is a data buffer to save the read data.
  *
- * @param size the size of buffer.
+ * @param size is the size of buffer.
  *
  * @return the actually read size on successful, otherwise negative returned.
  *
@@ -337,13 +337,13 @@ RTM_EXPORT(rt_device_read);
 /**
  * @brief This function will write some data to a device.
  *
- * @param dev the pointer of device driver structure.
+ * @param dev is the pointer of device driver structure.
  *
- * @param pos the position of written.
+ * @param pos is the position when writing.
  *
- * @param buffer the data buffer to be written to device.
+ * @param buffer is the data buffer to be written to device.
  *
- * @param size the size of buffer.
+ * @param size is the size of buffer.
  *
  * @return the actually written size on successful, otherwise negative returned.
  *
@@ -379,11 +379,11 @@ RTM_EXPORT(rt_device_write);
 /**
  * @brief This function will perform a variety of control functions on devices.
  *
- * @param dev the pointer of device driver structure.
+ * @param dev is the pointer of device driver structure.
  *
- * @param cmd the command sent to device.
+ * @param cmd is the command sent to device.
  *
- * @param arg the argument of command.
+ * @param arg is the argument of command.
  *
  * @return the result, -RT_ENOSYS for failed.
  */
@@ -406,11 +406,11 @@ RTM_EXPORT(rt_device_control);
  * @brief This function will set the reception indication callback function. This callback function
  *        is invoked when this device receives data.
  *
- * @param dev the pointer of device driver structure.
+ * @param dev is the pointer of device driver structure.
  *
- * @param rx_ind the indication callback function.
+ * @param rx_ind is the indication callback function.
  *
- * @return RT_EOK.
+ * @return RT_EOK
  */
 rt_err_t
 rt_device_set_rx_indicate(rt_device_t dev,
@@ -426,14 +426,14 @@ rt_device_set_rx_indicate(rt_device_t dev,
 RTM_EXPORT(rt_device_set_rx_indicate);
 
 /**
- * @brief This function will set the indication callback function when device has
- *        written data to physical hardware.
+ * @brief This function will set a callback function. The callback function
+ *        will be called when device has written data to physical hardware.
  *
- * @param dev the pointer of device driver structure.
+ * @param dev is the pointer of device driver structure.
  *
- * @param tx_done the indication callback function.
+ * @param tx_done is the indication callback function.
  *
- * @return RT_EOK.
+ * @return RT_EOK
  */
 rt_err_t
 rt_device_set_tx_complete(rt_device_t dev,
diff --git a/src/mem.c b/src/mem.c
index f661d49118..3c0816748e 100644
--- a/src/mem.c
+++ b/src/mem.c
@@ -266,7 +266,7 @@ void rt_system_heap_init(void *begin_addr, void *end_addr)
  *
  * @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)
 {
@@ -410,11 +410,11 @@ void *rt_malloc(rt_size_t size)
 RTM_EXPORT(rt_malloc);
 
 /**
- * @brief 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 rmem is the pointer to memory allocated by rt_malloc.
  *
- * @param newsize the required new size.
+ * @param newsize is the required new size.
  *
  * @return the changed memory block address.
  */
@@ -517,15 +517,15 @@ void *rt_realloc(void *rmem, rt_size_t newsize)
 RTM_EXPORT(rt_realloc);
 
 /**
- * @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.
+ * @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.
  *
- * @note 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  count is the number of objects to allocate.
  *
- * @param size size of the objects to allocate.
+ * @param  size is the size of one object to allocate.
  *
  * @return pointer to allocated memory / NULL pointer if there is an error.
  */
@@ -548,7 +548,7 @@ RTM_EXPORT(rt_calloc);
  * @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)
 {
diff --git a/src/mempool.c b/src/mempool.c
index 9b201c5f89..09a4955eee 100644
--- a/src/mempool.c
+++ b/src/mempool.c
@@ -33,7 +33,7 @@ static void (*rt_mp_free_hook)(struct rt_mempool *mp, void *block);
 
 /**
  * @brief This function will set a hook function, which will be invoked when a memory
- *        block is allocated from memory pool.
+ *        block is allocated from the memory pool.
  *
  * @param hook the hook function
  */
@@ -44,7 +44,7 @@ void rt_mp_alloc_sethook(void (*hook)(struct rt_mempool *mp, void *block))
 
 /**
  * @brief This function will set a hook function, which will be invoked when a memory
- *        block is released to memory pool.
+ *        block is released to the memory pool.
  *
  * @param hook the hook function
  */
@@ -63,18 +63,18 @@ void rt_mp_free_sethook(void (*hook)(struct rt_mempool *mp, void *block))
 /**@{*/
 
 /**
- * @brief 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  mp is the memory pool object.
  *
- * @param name the name of memory pool
+ * @param  name is the name of the memory pool.
  *
- * @param start the star address of memory pool
+ * @param  start is the start address of the memory pool.
  *
- * @param size the total size of memory pool
+ * @param  size is the total size of the memory pool.
  *
- * @param block_size the size for each block
+ * @param  block_size is the size for each block..
  *
  * @return RT_EOK
  */
@@ -129,9 +129,9 @@ rt_err_t rt_mp_init(struct rt_mempool *mp,
 RTM_EXPORT(rt_mp_init);
 
 /**
- * @brief 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
  */
@@ -179,11 +179,11 @@ RTM_EXPORT(rt_mp_detach);
  * @brief This function will create a mempool object and allocate the memory pool from
  *        heap.
  *
- * @param name the name of memory pool
+ * @param name is the name of memory pool.
  *
- * @param block_count the count of blocks in memory pool
+ * @param block_count is the count of blocks in memory pool.
  *
- * @param block_size the size for each block
+ * @param block_size is the size for each block.
  *
  * @return the created mempool object
  */
@@ -249,7 +249,7 @@ RTM_EXPORT(rt_mp_create);
 /**
  * @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
  */
@@ -301,9 +301,10 @@ RTM_EXPORT(rt_mp_delete);
 /**
  * @brief This function will allocate a block from memory pool.
  *
- * @param mp the memory pool object.
+ * @param mp is the memory pool object.
  *
- * @param time the waiting time.
+ * @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.
  */
@@ -399,9 +400,9 @@ void *rt_mp_alloc(rt_mp_t mp, rt_int32_t time)
 RTM_EXPORT(rt_mp_alloc);
 
 /**
- * @brief 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)
 {
diff --git a/src/object.c b/src/object.c
index de0140ebfa..66d5775bd7 100644
--- a/src/object.c
+++ b/src/object.c
@@ -123,7 +123,7 @@ void (*rt_object_put_hook)(struct rt_object *object);
  * @brief This function will set a hook function, which will be invoked when object
  *        attaches to kernel object system.
  *
- * @param hook the hook function.
+ * @param hook is the hook function.
  */
 void rt_object_attach_sethook(void (*hook)(struct rt_object *object))
 {
@@ -134,7 +134,7 @@ void rt_object_attach_sethook(void (*hook)(struct rt_object *object))
  * @brief This function will set a hook function, which will be invoked when object
  *        detaches from kernel object system.
  *
- * @param hook the hook function
+ * @param hook is the hook function
  */
 void rt_object_detach_sethook(void (*hook)(struct rt_object *object))
 {
@@ -152,7 +152,7 @@ void rt_object_detach_sethook(void (*hook)(struct rt_object *object))
  *            mailbox - mail is received by thread
  *            message queue - message is received by thread
  *
- * @param hook the hook function.
+ * @param hook is the hook function.
  */
 void rt_object_trytake_sethook(void (*hook)(struct rt_object *object))
 {
@@ -182,7 +182,7 @@ void rt_object_take_sethook(void (*hook)(struct rt_object *object))
  * @brief This function will set a hook function, which will be invoked when object
  *        is put to kernel object system.
  *
- * @param hook the hook function
+ * @param hook is the hook function
  */
 void rt_object_put_sethook(void (*hook)(struct rt_object *object))
 {
@@ -201,7 +201,7 @@ void rt_object_put_sethook(void (*hook)(struct rt_object *object))
 /**
  * @brief This function will return the specified type of object information.
  *
- * @param type the type of object, which can be
+ * @param type is the type of object, which can be
  *             RT_Object_Class_Thread/Semaphore/Mutex... etc
  *
  * @return the object type information or RT_NULL
@@ -221,7 +221,7 @@ RTM_EXPORT(rt_object_get_information);
 /**
  * @brief This function will return the length of object list in object container.
  *
- * @param type the type of object, which can be
+ * @param type is the type of object, which can be
  *             RT_Object_Class_Thread/Semaphore/Mutex... etc
  *
  * @return the length of object list
@@ -252,14 +252,14 @@ RTM_EXPORT(rt_object_get_length);
  * @brief This function will copy the object pointer of the specified type,
  *        with the maximum size specified by maxlen.
  *
- * @param type the type of object, which can be
+ * @param type is the type of object, which can be
  *             RT_Object_Class_Thread/Semaphore/Mutex... etc
  *
- * @param pointers the pointers will be saved to
+ * @param pointers is the pointer will be saved to.
  *
- * @param maxlen the maximum number of pointers can be saved
+ * @param maxlen is the maximum number of pointers can be saved.
  *
- * @return the copied number of object pointers
+ * @return the copied number of object pointers.
  */
 int rt_object_get_pointers(enum rt_object_class_type type, rt_object_t *pointers, int maxlen)
 {
@@ -296,11 +296,11 @@ RTM_EXPORT(rt_object_get_pointers);
  * @brief This function will initialize an object and add it to object system
  *        management.
  *
- * @param object the specified object to be initialized.
+ * @param object is the specified object to be initialized.
  *
- * @param type the object type.
+ * @param type is the object type.
  *
- * @param name the object name. In system, the object's name must be unique.
+ * @param name is the object name. In system, the object's name must be unique.
  */
 void rt_object_init(struct rt_object         *object,
                     enum rt_object_class_type type,
@@ -397,9 +397,9 @@ void rt_object_detach(rt_object_t object)
 /**
  * @brief This function will allocate an object from object system.
  *
- * @param type the type of object
+ * @param type is the type of object.
  *
- * @param name the object name. In system, the object's name must be unique.
+ * @param name is the object name. In system, the object's name must be unique.
  *
  * @return object
  */
@@ -467,7 +467,7 @@ rt_object_t rt_object_allocate(enum rt_object_class_type type, const char *name)
 /**
  * @brief This function will delete an object and release object memory.
  *
- * @param object the specified object to be deleted.
+ * @param object is the specified object to be deleted.
  */
 void rt_object_delete(rt_object_t object)
 {
@@ -502,7 +502,7 @@ void rt_object_delete(rt_object_t object)
  * @note  Normally, the system object is a static object and the type
  *        of object set to RT_Object_Class_Static.
  *
- * @param object the specified object to be judged.
+ * @param object is the specified object to be judged.
  *
  * @return RT_TRUE if a system object, RT_FALSE for others.
  */
@@ -521,7 +521,7 @@ rt_bool_t rt_object_is_systemobject(rt_object_t object)
  * @brief This function will return the type of object without
  *        RT_Object_Class_Static flag.
  *
- * @param object the specified object to be get type.
+ * @param object is the specified object to be get type.
  *
  * @return the type of object.
  */
@@ -537,9 +537,9 @@ rt_uint8_t rt_object_get_type(rt_object_t object)
  * @brief This function will find specified name object from object
  *        container.
  *
- * @param name the specified name of object.
+ * @param name is the specified name of object.
  *
- * @param type the type of object
+ * @param type is the type of object
  *
  * @return the found object or RT_NULL if there is no this object
  * in object container.
diff --git a/src/scheduler.c b/src/scheduler.c
index dc0073d097..6ef02f3d3c 100644
--- a/src/scheduler.c
+++ b/src/scheduler.c
@@ -61,7 +61,7 @@ static void (*rt_scheduler_switch_hook)(struct rt_thread *tid);
  * @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))
 {
@@ -72,7 +72,7 @@ void rt_scheduler_sethook(void (*hook)(struct rt_thread *from, struct rt_thread
  * @brief This function will set a hook function, which will be invoked when context
  *        switch happens.
  *
- * @param hook the hook function.
+ * @param hook is the hook function.
  */
 void rt_scheduler_switch_sethook(void (*hook)(struct rt_thread *tid))
 {
@@ -235,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)
 {
@@ -276,9 +275,9 @@ void rt_system_scheduler_start(void)
 /**
  * @brief This function will handle IPI interrupt and do a scheduling in system.
  *
- * @param vector the number of IPI interrupt for system scheduling.
+ * @param vector is the number of IPI interrupt for system scheduling.
  *
- * @param param use RT_NULL.
+ * @param param is not used, and can be set to RT_NULL.
  *
  * @note this function should be invoke or register as ISR in BSP.
  */
@@ -411,8 +410,8 @@ __exit:
 }
 #else
 /**
- * @brief 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)
 {
@@ -540,7 +539,7 @@ __exit:
 #endif /* RT_USING_SMP */
 
 /**
- * @brief This function checks if a scheduling is needed after IRQ context. If yes,
+ * @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.
  */
@@ -636,12 +635,12 @@ void rt_scheduler_do_irq_switch(void *context)
 #endif /* RT_USING_SMP */
 
 /**
- * @brief 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
+ * @param thread is the thread to be inserted.
  *
- * @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_insert_thread(struct rt_thread *thread)
@@ -746,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)
diff --git a/src/slab.c b/src/slab.c
index 87acb17da8..8e0ce7bc83 100644
--- a/src/slab.c
+++ b/src/slab.c
@@ -277,9 +277,9 @@ void *rt_page_alloc(rt_size_t npages)
 /**
  * @brief Free memory by page.
  *
- * @param addr the head address of first page.
+ * @param addr is the head address of first page.
  *
- * @param npages the number of pages.
+ * @param npages is the number of pages.
  */
 void rt_page_free(void *addr, rt_size_t npages)
 {
@@ -482,7 +482,7 @@ rt_inline int zoneindex(rt_size_t *bytes)
  *         - the nbytes is less than zero.
  *         - there is no nbytes sized memory valid in system.
  *
- * @param size the size of memory to be allocated.
+ * @param size is the size of memory to be allocated.
  *
  * @return the allocated memory.
  */
@@ -681,9 +681,9 @@ RTM_EXPORT(rt_malloc);
 /**
  * @brief This function will change the size of previously allocated memory block.
  *
- * @param ptr the previously allocated memory block.
+ * @param ptr is the previously allocated memory block.
  *
- * @param size the new size of memory block.
+ * @param size is the new size of memory block.
  *
  * @return the allocated memory.
  */
@@ -754,9 +754,9 @@ RTM_EXPORT(rt_realloc);
  *
  * @note The allocated memory is filled with bytes of value zero.
  *
- * @param count number of objects to allocate.
+ * @param count is the number of objects to allocate.
  *
- * @param size size of the objects to allocate.
+ * @param size is the size of the objects to allocate.
  *
  * @return pointer to allocated memory / NULL pointer if there is an error.
  */
@@ -780,7 +780,7 @@ RTM_EXPORT(rt_calloc);
  *
  * @note The released memory block is taken back to system heap.
  *
- * @param ptr the address of memory which will be released
+ * @param ptr is the address of memory which will be released
  */
 void rt_free(void *ptr)
 {

From fe5d506ef25ac7dc4b4516c9cb3ed38d0e38d619 Mon Sep 17 00:00:00 2001
From: yangjie <yangjiexaut@126.com>
Date: Mon, 13 Sep 2021 16:10:44 +0800
Subject: [PATCH 4/4] =?UTF-8?q?=E3=80=90=E5=A2=9E=E5=8A=A0=E3=80=91memheap?=
 =?UTF-8?q?.c?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/memheap.c | 141 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 130 insertions(+), 11 deletions(-)

diff --git a/src/memheap.c b/src/memheap.c
index e09f5c4bce..8422b1d802 100644
--- a/src/memheap.c
+++ b/src/memheap.c
@@ -39,6 +39,13 @@
 #define MEMITEM(ptr)            (struct rt_memheap_item*)((rt_uint8_t*)ptr - RT_MEMHEAP_SIZE)
 
 #ifdef RT_USING_MEMTRACE
+/**
+ * @brief This function will set a new name for memheap.
+ *
+ * @param item is a pointer point to a memheap object.
+ *
+ * @param name is the new name to be set.
+ */
 rt_inline void rt_memheap_setname(struct rt_memheap_item *item, const char *name)
 {
     int index;
@@ -64,6 +71,13 @@ rt_inline void rt_memheap_setname(struct rt_memheap_item *item, const char *name
     }
 }
 
+/**
+ * @brief This function will set a new name for memheap.
+ *
+ * @param ptr is a pointer point to a memheap object.
+ *
+ * @param name is the new name to be set.
+ */
 void rt_mem_set_tag(void *ptr, const char *name)
 {
     struct rt_memheap_item *item;
@@ -76,16 +90,28 @@ void rt_mem_set_tag(void *ptr, const char *name)
 }
 #endif /* RT_USING_MEMTRACE */
 
-/*
- * The initialized memory pool will be:
- * +-----------------------------------+--------------------------+
- * | whole freed memory block          | Used Memory Block Tailer |
- * +-----------------------------------+--------------------------+
+/**
+ * @brief   This function initializes a piece of memory called memheap.
  *
- * block_list --> whole freed memory block
+ * @note    The initialized memory pool will be:
+ *          +-----------------------------------+--------------------------+
+ *          | whole freed memory block          | Used Memory Block Tailer |
+ *          +-----------------------------------+--------------------------+
  *
- * The length of Used Memory Block Tailer is 0,
- * which is prevents block merging across list
+ *          block_list --> whole freed memory block
+ *
+ *          The length of Used Memory Block Tailer is 0,
+ *          which is prevents block merging across list
+ *
+ * @param   memheap is a pointer of the memheap object.
+ *
+ * @param   name is the name of the memheap.
+ *
+ * @param   start_addr is the start address of the memheap.
+ *
+ * @param   size is the size of the memheap.
+ *
+ * @return  RT_EOK
  */
 rt_err_t rt_memheap_init(struct rt_memheap *memheap,
                          const char        *name,
@@ -165,6 +191,13 @@ rt_err_t rt_memheap_init(struct rt_memheap *memheap,
 }
 RTM_EXPORT(rt_memheap_init);
 
+/**
+ * @brief   This function will remove a memheap from the system.
+ *
+ * @param   heap is a pointer of memheap object.
+ *
+ * @return  RT_EOK
+ */
 rt_err_t rt_memheap_detach(struct rt_memheap *heap)
 {
     RT_ASSERT(heap);
@@ -179,6 +212,15 @@ rt_err_t rt_memheap_detach(struct rt_memheap *heap)
 }
 RTM_EXPORT(rt_memheap_detach);
 
+/**
+ * @brief  Allocate a block of memory with a minimum of 'size' bytes on memheap.
+ *
+ * @param   heap is a pointer for memheap object.
+ *
+ * @param   size is the minimum size of the requested block in bytes.
+ *
+ * @return  the pointer to allocated memory or NULL if no free memory was found.
+ */
 void *rt_memheap_alloc(struct rt_memheap *heap, rt_size_t size)
 {
     rt_err_t result;
@@ -336,6 +378,18 @@ void *rt_memheap_alloc(struct rt_memheap *heap, rt_size_t size)
 }
 RTM_EXPORT(rt_memheap_alloc);
 
+/**
+ * @brief This function will change the size of previously allocated memory block.
+ *
+ * @param heap is a pointer to the memheap object, which will reallocate
+ *             memory from the block
+ *
+ * @param ptr is a pointer to start address of memory.
+ *
+ * @param newsize is the required new size.
+ *
+ * @return the changed memory block address.
+ */
 void *rt_memheap_realloc(struct rt_memheap *heap, void *ptr, rt_size_t newsize)
 {
     rt_err_t result;
@@ -556,6 +610,12 @@ void *rt_memheap_realloc(struct rt_memheap *heap, void *ptr, rt_size_t newsize)
 }
 RTM_EXPORT(rt_memheap_realloc);
 
+/**
+ * @brief This function will release the allocated memory block by
+ *        rt_malloc. The released memory block is taken back to system heap.
+ *
+ * @param ptr the address of memory which will be released.
+ */
 void rt_memheap_free(void *ptr)
 {
     rt_err_t result;
@@ -680,7 +740,13 @@ static void _memheap_dump_tag(struct rt_memheap_item *item)
 
     rt_kprintf("%.*s", 2 * sizeof(void *), name);
 }
-
+/**
+ * @brief   This function will print the memheap infomation.
+ *
+ * @param   heap is the pointer  to the memheap to get information.
+ *
+ * @return  0
+ */
 int rt_memheap_dump(struct rt_memheap *heap)
 {
     struct rt_memheap_item *item, *end;
@@ -757,6 +823,13 @@ MSH_CMD_EXPORT(memheaptrace, dump memory trace information);
 #ifdef RT_USING_MEMHEAP_AS_HEAP
 static struct rt_memheap _heap;
 
+/**
+ * @brief   This function initializes a heap for system.
+ *
+ * @param   begin_addr is the start address of the memory.
+ *
+ * @param   end_addr is the end address of the memory.
+ */
 void rt_system_heap_init(void *begin_addr, void *end_addr)
 {
     RT_ASSERT((rt_uint32_t)end_addr > (rt_uint32_t)begin_addr);
@@ -768,6 +841,11 @@ void rt_system_heap_init(void *begin_addr, void *end_addr)
                     (rt_uint32_t)end_addr - (rt_uint32_t)begin_addr);
 }
 
+/**
+ * @brief Allocate a block of memory with a minimum of 'size' bytes.
+ *
+ * @param size is the minimum size of the requested block in bytes.
+ */
 void *rt_malloc(rt_size_t size)
 {
     void *ptr;
@@ -804,7 +882,6 @@ void *rt_malloc(rt_size_t size)
         }
     }
 
-
 #ifdef RT_USING_MEMTRACE
     if (ptr == RT_NULL)
     {
@@ -826,12 +903,27 @@ void *rt_malloc(rt_size_t size)
 }
 RTM_EXPORT(rt_malloc);
 
+/**
+ * @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.
+ */
 void rt_free(void *rmem)
 {
     rt_memheap_free(rmem);
 }
 RTM_EXPORT(rt_free);
 
+/**
+ * @brief This function will change the size of previously allocated memory block.
+ *
+ * @param rmem is the pointer to memory allocated by rt_malloc.
+ *
+ * @param newsize is the required new size.
+ *
+ * @return the changed memory block address.
+ */
 void *rt_realloc(void *rmem, rt_size_t newsize)
 {
     void *new_ptr;
@@ -892,6 +984,19 @@ void *rt_realloc(void *rmem, rt_size_t newsize)
 }
 RTM_EXPORT(rt_realloc);
 
+/**
+ * @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.
+ *
+ * @note   The allocated memory is filled with bytes of value zero.
+ *
+ * @param  count is the number of objects to allocate.
+ *
+ * @param  size is the size of one object to allocate.
+ *
+ * @return pointer to allocated memory pointer.
+ */
 void *rt_calloc(rt_size_t count, rt_size_t size)
 {
     void *ptr;
@@ -922,6 +1027,16 @@ void *rt_calloc(rt_size_t count, rt_size_t size)
 }
 RTM_EXPORT(rt_calloc);
 
+/**
+* @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)
@@ -940,12 +1055,16 @@ void rt_memory_info(rt_uint32_t *total,
 
 #ifdef RT_USING_MEMTRACE
 
+/**
+ * @brief  This function will print the used memheap infomation.
+ *
+ * @param  memheap is a pointer of the memheap object.
+ */
 void dump_used_memheap(struct rt_memheap *mh)
 {
     struct rt_memheap_item *header_ptr;
     rt_uint32_t block_size;
 
-
     rt_kprintf("\nmemory heap address:\n");
     rt_kprintf("heap_ptr: 0x%08x\n", mh->start_addr);
     rt_kprintf("free    : 0x%08x\n", mh->available_size);