[kernel] update comments

Author: yangjie11

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,

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

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