Merge pull request #5040 from yangjie11/comments

[kernel]Normalized kernel API annotation

1 files changed, 60 insertions, 46 deletions

diff --git a/src/device.c b/src/device.c
index a9c244d306..6e22c2b692 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 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
  */