Merge pull request #5040 from yangjie11/comments

[kernel]Normalized kernel API annotation

Author: BernardXiong

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 a 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 is the pointer of device driver structure.
+ *
+ * @param name is the device driver's name.
+ *
+ * @param flags is 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 is 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 is 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 is the type of the device object.
+ *
+ * @param attach_size is 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 is a 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 is 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 is the pointer of device driver structure.
  *
- * @param dev the pointer of device driver structure
- * @param oflag the flags for device open
+ * @param oflag is the flags for device open.
  *
- * @return the result
+ * @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 is 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 is the pointer of device driver structure.
+ *
+ * @param pos is the position when reading.
+ *
+ * @param buffer is a data buffer to save the read data.
  *
- * @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 size is 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 is the pointer of device driver structure.
+ *
+ * @param pos is the position when writing.
+ *
+ * @param buffer is the data buffer to be written to device.
+ *
+ * @param size is 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 is the pointer of device driver structure.
  *
- * @param dev the pointer of device driver structure
- * @param cmd the command sent to device
- * @param arg the argument of command
+ * @param cmd is the command sent to device.
  *
- * @return the result
+ * @param arg is 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,11 +403,12 @@ 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 is the pointer of device driver structure.
  *
- * @param dev the pointer of device driver structure
- * @param rx_ind the indication callback function
+ * @param rx_ind is the indication callback function.
  *
  * @return RT_EOK
  */
@@ -413,11 +426,12 @@ 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 a callback function. The callback function
+ *        will be called when device has written data to physical hardware.
+ *
+ * @param dev is the pointer of device driver structure.
  *
- * @param dev the pointer of device driver structure
- * @param tx_done the indication callback function
+ * @param tx_done is the indication callback function.
  *
  * @return RT_EOK
  */

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