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] [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)
 {